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CHAPTER 1 


Introduction 


Tue Java® programming language is a general-purpose, concurrent, class- 
based, object-oriented language. It is designed to be simple enough that many 
programmers can achieve fluency in the language. The Java programming language 
is related to C and C++ but is organized rather differently, with a number of aspects 
of C and C++ omitted and a few ideas from other languages included. It is intended 
to be a production language, not a research language, and so, as C. A. R. Hoare 
suggested in his classic paper on language design, the design has avoided including 
new and untested features. 


The Java programming language is strongly and statically typed. This specification 
clearly distinguishes between the compile-time errors that can and must be detected 
at compile time, and those that occur at run time. Compile time normally consists 
of translating programs into a machine-independent byte code representation. 
Run-time activities include loading and linking of the classes needed to execute 
a program, optional machine code generation and dynamic optimization of the 
program, and actual program execution. 


The Java programming language is a relatively high-level language, in that details 
of the machine representation are not available through the language. It includes 
automatic storage management, typically using a garbage collector, to avoid 
the safety problems of explicit deallocation (as in C's free or C++'s delete). 
High-performance garbage-collected implementations can have bounded pauses to 
support systems programming and real-time applications. The language does not 
include any unsafe constructs, such as array accesses without index checking, since 
such unsafe constructs would cause a program to behave in an unspecified way. 


The Java programming language is normally compiled to the bytecode instruction 
set and binary format defined in The Java Virtual Machine Specification, Java SE 
12 Edition. 


Ll 


Organization of the Specification INTRODUCTION 


1.1 Organization of the Specification 


Chapter 2 describes grammars and the notation used to present the lexical and 
syntactic grammars for the language. 


Chapter 3 describes the lexical structure of the Java programming language, which 
is based on C and C++. The language is written in the Unicode character set. It 
supports the writing of Unicode characters on systems that support only ASCIL. 


Chapter 4 describes types, values, and variables. Types are subdivided into 
primitive types and reference types. 


The primitive types are defined to be the same on all machines and in all 
implementations, and are various sizes of two's-complement integers, single- and 
double-precision IEEE 754 standard floating-point numbers, a boolean type, and 
a Unicode character char type. Values of the primitive types do not share state. 


Reference types are the class types, the interface types, and the array types. The 
reference types are implemented by dynamically created objects that are either 
instances of classes or arrays. Many references to each object can exist. All objects 
(including arrays) support the methods of the class object, which is the (single) 
root of the class hierarchy. A predefined st ring class supports Unicode character 
strings. Classes exist for wrapping primitive values inside of objects. In many 
cases, wrapping and unwrapping is performed automatically by the compiler (in 
which case, wrapping is called boxing, and unwrapping is called unboxing). Class 
and interface declarations may be generic, that is, they may be parameterized by 
other reference types. Such declarations may then be invoked with specific type 
arguments. 


Variables are typed storage locations. A variable of a primitive type holds a value 
of that exact primitive type. A variable of a class type can hold a null reference or 
a reference to an object whose type is that class type or any subclass of that class 
type. A variable of an interface type can hold a null reference or a reference to an 
instance of any class that implements the interface. A variable of an array type can 
hold a null reference or a reference to an array. A variable of class type object can 
hold a null reference or a reference to any object, whether class instance or array. 


Chapter 5 describes conversions and numeric promotions. Conversions change the 
compile-time type and, sometimes, the value of an expression. These conversions 
include the boxing and unboxing conversions between primitive types and 
reference types. Numeric promotions are used to convert the operands of a numeric 
operator to a common type where an operation can be performed. There are no 


INTRODUCTION Organization of the Specification 


loopholes in the language; casts on reference types are checked at run time to ensure 
type safety. 


Chapter 6 describes declarations and names, and how to determine what names 
mean (that is, which declaration a name denotes). The Java programming language 
does not require classes and interfaces, or their members, to be declared before 
they are used. Declaration order is significant only for local variables, local classes, 
and the order of field initializers in a class or interface. Recommended naming 
conventions that make for more readable programs are described here. 


Chapter 7 describes the structure of a program, which is organized into packages. 
The members of a package are classes, interfaces, and subpackages. Packages, 
and consequently their members, have names in a hierarchical name space; the 
Internet domain name system can usually be used to form unique package names. 
Compilation units contain declarations of the classes and interfaces that are 
members of a given package, and may import classes and interfaces from other 
packages to give them short names. 


Packages may be grouped into modules that serve as building blocks in the 
construction of very large programs. The declaration of a module specifies which 
other modules (and thus packages, and thus classes and interfaces) are required in 
order to compile and run code in its own packages. 


The Java programming language supports limitations on external access to the 
members of packages, classes, and interfaces. The members of a package may be 
accessible solely by other members in the same package, or by members in other 
packages of the same module, or by members of packages in different modules. 
Similar constraints apply to the members of classes and interfaces. 


Chapter 8 describes classes. The members of classes are classes, interfaces, fields 
(variables) and methods. Class variables exist once per class. Class methods operate 
without reference to a specific object. Instance variables are dynamically created 
in objects that are instances of classes. Instance methods are invoked on instances 
of classes; such instances become the current object this during their execution, 
supporting the object-oriented programming style. 


Classes support single inheritance, in which each class has a single superclass. Each 
class inherits members from its superclass, and ultimately from the class object. 
Variables of a class type can reference an instance of that class or of any subclass of 
that class, allowing new types to be used with existing methods, polymorphically. 


Classes support concurrent programming with synchronized methods. Methods 
declare the checked exceptions that can arise from their execution, which allows 
compile-time checking to ensure that exceptional conditions are handled. Objects 
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can declare a finalize method that will be invoked before the objects are discarded 
by the garbage collector, allowing the objects to clean up their state. 


For simplicity, the language has neither declaration "headers" separate from the 
implementation of a class nor separate type and class hierarchies. 


A special form of classes, enums, support the definition of small sets of values and 
their manipulation in a type safe manner. Unlike enumerations in other languages, 
enums are objects and may have their own methods. 


Chapter 9 describes interfaces. The members of interfaces are classes, interfaces, 
constant fields, and methods. Classes that are otherwise unrelated can implement 
the same interface. A variable of an interface type can contain a reference to any 
object that implements the interface. 


Classes and interfaces support multiple inheritance from interfaces. A class that 
implements one or more interfaces may inherit instance methods from both its 
superclass and its superinterfaces. 


Annotation types are specialized interfaces used to annotate declarations. Such 
annotations are not permitted to affect the semantics of programs in the Java 
programming language in any way. However, they provide useful input to various 
tools. 


Chapter 10 describes arrays. Array accesses include bounds checking. Arrays are 
dynamically created objects and may be assigned to variables of type object. The 
language supports arrays of arrays, rather than multidimensional arrays. 


Chapter 11 describes exceptions, which are nonresuming and fully integrated with 
the language semantics and concurrency mechanisms. There are three kinds of 
exceptions: checked exceptions, run-time exceptions, and errors. The compiler 
ensures that checked exceptions are properly handled by requiring that a method 
or constructor can result in a checked exception only if the method or constructor 
declares it. This provides compile-time checking that exception handlers exist, and 
aids programming in the large. Most user-defined exceptions should be checked 
exceptions. Invalid operations in the program detected by the Java Virtual Machine 
result in run-time exceptions, such as Nul1PointerException. Errors result from 
failures detected by the Java Virtual Machine, such as outofMemoryError. Most 
simple programs do not try to handle errors. 


Chapter 12 describes activities that occur during execution of a program. A 
program is normally stored as binary files representing compiled classes and 
interfaces. These binary files can be loaded into a Java Virtual Machine, linked to 
other classes and interfaces, and initialized. 
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After initialization, class methods and class variables may be used. Some classes 
may be instantiated to create new objects of the class type. Objects that are class 
instances also contain an instance of each superclass of the class, and object 
creation involves recursive creation of these superclass instances. 


When an object is no longer referenced, it may be reclaimed by the garbage 
collector. If an object declares a finalizer, the finalizer is executed before the object 
is reclaimed to give the object a last chance to clean up resources that would not 
otherwise be released. When a class is no longer needed, it may be unloaded. 


Chapter 13 describes binary compatibility, specifying the impact of changes to 
types on other types that use the changed types but have not been recompiled. These 
considerations are of interest to developers of types that are to be widely distributed, 
in a continuing series of versions, often through the Internet. Good program 
development environments automatically recompile dependent code whenever a 
type is changed, so most programmers need not be concerned about these details. 


Chapter 14 describes blocks and statements, which are based on C and C++. 
The language has no goto statement, but includes labeled break and continue 
statements. Unlike C, the Java programming language requires boolean (or 
Boolean) expressions in control-flow statements, and does not convert types to 
boolean implicitly (except through unboxing), in the hope of catching more errors 
at compile time. A synchronized statement provides basic object-level monitor 
locking. A try statement can include catch and finally clauses to protect against 
non-local control transfers. 


Chapter 15 describes expressions. This document fully specifies the (apparent) 
order of evaluation of expressions, for increased determinism and portability. 
Overloaded methods and constructors are resolved at compile time by picking the 
most specific method or constructor from those which are applicable. 


Chapter 16 describes the precise way in which the language ensures that 
local variables are definitely set before use. While all other variables are 
automatically initialized to a default value, the Java programming language does 
not automatically initialize local variables in order to avoid masking programming 
errors. 


Chapter 17 describes the semantics of threads and locks, which are based on 
the monitor-based concurrency originally introduced with the Mesa programming 
language. The Java programming language specifies a memory model for shared- 
memory multiprocessors that supports high-performance implementations. 


Chapter 18 describes a variety of type inference algorithms used to test applicability 
of generic methods and to infer types in a generic method invocation. 


Ld 


1.2 


Example Programs INTRODUCTION 


Chapter 19 presents a syntactic grammar for the language. 


1.2 Example Programs 


Most of the example programs given in the text are ready to be executed and are 
similar in form to: 


class Test { 
public static void main(String[] args) { 
for (int i = 0; i < args.length; i++) 
System.out.print(i == 0 ? args[i] : " " + args[i]); 
System.out.println(); 


} 


On a machine with the Oracle JDK installed, this class, stored in the file Test . java, 
can be compiled and executed by giving the commands: 


javac Test.java 
java Test Hello, world. 


producing the output: 


Hello, world. 


1.3. Notation 


Throughout this specification we refer to classes and interfaces drawn from the 
Java SE Platform API. Whenever we refer to a class or interface (other than those 
declared in an example) using a single identifier N, the intended reference is to the 
class or interface named N in the package java.1lang. We use the canonical name 
($6.7) for classes or interfaces from packages other than java.lang. 


Non-normative information, designed to clarify the specification, is given in 
smaller, indented text. 


This is non-normative information. It provides intuition, rationale, advice, examples, etc. 


The type system of the Java programming language occasionally relies on the 
notion of a substitution. The notation [F,:=T,,...,Fn:=Tn] denotes substitution 
of F; by rT; forl <i<n. 
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1.4 Relationship to Predefined Classes and Interfaces 


As noted above, this specification often refers to classes of the Java SE 
Platform API. In particular, some classes have a special relationship with 
the Java programming language. Examples include classes such as object, 
Class, ClassLoader, String, Thread, and the classes and interfaces in package 
java.lang.reflect, among others. This specification constrains the behavior of 
such classes and interfaces, but does not provide a complete specification for them. 
The reader is referred to the Java SE Platform API documentation. 


Consequently, this specification does not describe reflection in any detail. 
Many linguistic constructs have analogs in the Core Reflection API 
(java.lang.reflect) and the Language Model API (javax.lang.mode1), but 
these are generally not discussed here. For example, when we list the ways in which 
an object can be created, we generally do not include the ways in which the Core 
Reflection API can accomplish this. Readers should be aware of these additional 
mechanisms even though they are not mentioned in the text. 


1.5 Feedback 


Readers are invited to report technical errors and ambiguities in The Java® 
Language Specification to jls-jvms-spec-comments@openjdk. java.net. 


Questions concerning the behavior of javac (the reference compiler for the Java 
programming language), and in particular its conformance to this specification, 
may be sent to compiler-dev@openjdk. java.net. 
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Grammars 


THIS chapter describes the context-free grammars used in this specification to 
define the lexical and syntactic structure of a program. 


2.1 Context-Free Grammars 


A context-free grammar consists of a number of productions. Each production has 
an abstract symbol called a nonterminal as its left-hand side, and a sequence of 
one or more nonterminal and terminal symbols as its right-hand side. For each 
grammar, the terminal symbols are drawn from a specified alphabet. 


Starting from a sentence consisting of a single distinguished nonterminal, called the 
goal symbol, a given context-free grammar specifies a language, namely, the set of 
possible sequences of terminal symbols that can result from repeatedly replacing 
any nonterminal in the sequence with a right-hand side of a production for which 
the nonterminal is the left-hand side. 


2.2 The Lexical Grammar 


A lexical grammar for the Java programming language is given in §3 (Lexical 
Structure). This grammar has as its terminal symbols the characters of the Unicode 
character set. It defines a set of productions, starting from the goal symbol /nput 
(§3.5), that describe how sequences of Unicode characters (§3.1) are translated into 
a sequence of input elements (§3.5). 


These input elements, with white space (§3.6) and comments (§3.7) discarded, 
form the terminal symbols for the syntactic grammar for the Java programming 
language and are called tokens (§3.5). These tokens are the identifiers (§3.8), 
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keywords (§3.9), literals ($3.10), separators (§3.11), and operators (§3.12) of the 
Java programming language. 


2.3. The Syntactic Grammar 


The syntactic grammar for the Java programming language is given in Chapters 
4, 6-10, 14, and 15. This grammar has as its terminal symbols the tokens defined 
by the lexical grammar. It defines a set of productions, starting from the goal 
symbol CompilationUnit (§7.3), that describe how sequences of tokens can form 
syntactically correct programs. 


For convenience, the syntactic grammar is presented all together in Chapter 19. 


2.4 Grammar Notation 


Terminal symbols are shown in fixed width font in the productions of the lexical 
and syntactic grammars, and throughout this specification whenever the text is 
directly referring to such a terminal symbol. These are to appear in a program 
exactly as written. 


Nonterminal symbols are shown in italic type. The definition of a nonterminal is 
introduced by the name of the nonterminal being defined, followed by a colon. One 
or more alternative definitions for the nonterminal then follow on succeeding lines. 


For example, the syntactic production: 


IfThenStatement: 
if ( Expression ) Statement 


states that the nonterminal /fThenStatement represents the token if, followed by a left 
parenthesis token, followed by an Expression, followed by a right parenthesis token, 
followed by a Statement. 


The syntax /x/ on the right-hand side of a production denotes zero or more 
occurrences of x. 


For example, the syntactic production: 


ArgumentList: 
Argument {, Argument} 
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states that an ArgumentList consists of an Argument, followed by zero or more occurrences 
of acomma and an Argument. The result is that an ArgumentList may contain any positive 
number of arguments. 


The syntax /x/ on the right-hand side of a production denotes zero or one 
occurrences of x. That is, x is an optional symbol. The alternative which contains 
the optional symbol actually defines two alternatives: one that omits the optional 
symbol and one that includes it. 


This means that: 


BreakStatement: 
break [Identifier] ; 


is a convenient abbreviation for: 


BreakStatement: 
break ; 
break Identifier ; 


As another example, it means that: 


BasicForStatement: 
for ( [ForInit] ; [Expression] ; [ForUpdate] ) Statement 


is a convenient abbreviation for: 


BasicForStatement: 
for (; [Expression] ; [ForUpdate] ) Statement 
for ( Forlnit ; [Expression] ; [ForUpdate] ) Statement 


which in turn is an abbreviation for: 


BasicForStatement: 
for (; ; [ForUpdate] ) Statement 
for (; Expression ; [ForUpdate] ) Statement 
for ( Forlnit ; ; [ForUpdate] ) Statement 
for ( Forlnit ; Expression ; [ForUpdate] ) Statement 


which in turn is an abbreviation for: 
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BasicForStatement: 
for (; ; ) Statement 


for (; ; ForUpdate ) Statement 
for (; Expression ; ) Statement 
for (; Expression ; ForUpdate ) Statement 


( 
( 
( 
for ( Forlnit ; ; ) Statement 
( 
( 
( 


for ( Forlnit ; ; ForUpdate ) Statement 
for ( Forlnit ; Expression ; ) Statement 
for ( Forlnit ; Expression ; ForUpdate ) Statement 


so the nonterminal BasicForStatement actually has eight alternative right-hand sides. 


A very long right-hand side may be continued on a second line by clearly indenting 
the second line. 


For example, the syntactic grammar contains this production: 


NormalClassDeclaration: 
{ClassModifier} class Typeldentifier [TypeParameters] 
[Superclass] [Superinterfaces] ClassBody 


which defines one right-hand side for the nonterminal NormalClassDeclaration. 


The phrase (one of) on the right-hand side of a production signifies that each of the 
symbols on the following line or lines is an alternative definition. 


For example, the lexical grammar contains the production: 


ZeroTotThree: 
(one of) 


Oe 253 


which is merely a convenient abbreviation for: 


ZeroTotThree: 
0 


1 
2 
3 
When an alternative in a production appears to be a token, it represents the sequence 
of characters that would make up such a token. 
Thus, the production: 


BooleanLiteral: 


(one of) 


true false 
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is shorthand for: 


BooleanLiteral: 
true 
false 


The right-hand side of a production may specify that certain expansions are not 
permitted by using the phrase "but not" and then indicating the expansions to be 
excluded. 


For example: 


Identifier: 
IdentifierChars but not a Keyword or BooleanLiteral or NullLiteral 


Finally, a few nonterminals are defined by a narrative phrase in roman type where 
it would be impractical to list all the alternatives. 


For example: 


RawInputCharacter: 
any Unicode character 
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Lexical Structure 


Tus chapter specifies the lexical structure of the Java programming language. 


Programs are written in Unicode (§3.1), but lexical translations are provided (§3.2) 
so that Unicode escapes (§3.3) can be used to include any Unicode character using 
only ASCII characters. Line terminators are defined (§3.4) to support the different 
conventions of existing host systems while maintaining consistent line numbers. 


The Unicode characters resulting from the lexical translations are reduced to a 
sequence of input elements (§3.5), which are white space (§3.6), comments (§3.7), 
and tokens. The tokens are the identifiers ($3.8), keywords (§3.9), literals ($3.10), 
separators (§3.11), and operators (§3.12) of the syntactic grammar. 


3.1 Unicode 


Programs are written using the Unicode character set. Information about this 
character set and its associated character encodings may be found at nttp:// 


www.unicode.org/. 


The Java SE Platform tracks the Unicode Standard as it evolves. The precise 
version of Unicode used by a given release is specified in the documentation of 
the class Character. 


Versions of the Java programming language prior to JDK 1.1 used Unicode 1.1.5. Upgrades 
to newer versions of the Unicode Standard occurred in JDK 1.1 (to Unicode 2.0), JDK 1.1.7 
(to Unicode 2.1), Java SE 1.4 (to Unicode 3.0), Java SE 5.0 (to Unicode 4.0), Java SE 7 
(to Unicode 6.0), Java SE 8 (to Unicode 6.2), Java SE 9 (to Unicode 8.0), Java SE 11 (to 
Unicode 10.0), and Java SE 12 (to Unicode 11.0). 


The Unicode standard was originally designed as a fixed-width 16-bit character 
encoding. It has since been changed to allow for characters whose representation 
requires more than 16 bits. The range of legal code points is now U+0000 
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to U+10FFFF, using the hexadecimal U+n notation. Characters whose code 
points are greater than U+FFFF are called supplementary characters. To represent 
the complete range of characters using only 16-bit units, the Unicode standard 
defines an encoding called UTF-16. In this encoding, supplementary characters are 
represented as pairs of 16-bit code units, the first from the high-surrogates range, 
(U+D800 to U+DBFFP), the second from the low-surrogates range (U+DCO00 to U 
+DFFF). For characters in the range U+0000 to U+FFFF, the values of code points 
and UTF-16 code units are the same. 


The Java programming language represents text in sequences of 16-bit code units, 
using the UTF-16 encoding. 


Some APIs of the Java SE Platform, primarily in the Character class, use 32-bit integers 
to represent code points as individual entities. The Java SE Platform provides methods to 
convert between 16-bit and 32-bit representations. 


This specification uses the terms code point and UTF-16 code unit where the 
representation is relevant, and the generic term character where the representation 
is irrelevant to the discussion. 


Except for comments (§3.7), identifiers, and the contents of character and string 
literals (§3.10.4, §3.10.5), all input elements (§3.5) in a program are formed 
only from ASCII characters (or Unicode escapes (§3.3) which result in ASCII 
characters). 


ASCII (ANSI X3.4) is the American Standard Code for Information Interchange. The first 
128 characters of the Unicode UTF-16 encoding are the ASCII characters. 


3.2 Lexical Translations 


A raw Unicode character stream is translated into a sequence of tokens, using the 
following three lexical translation steps, which are applied in turn: 


1. Atranslation of Unicode escapes (§3.3) in the raw stream of Unicode characters 
to the corresponding Unicode character. A Unicode escape of the form \uxxxx, 
where xxxx is a hexadecimal value, represents the UTF-16 code unit whose 
encoding is xxxx. This translation step allows any program to be expressed 
using only ASCII characters. 


2. A translation of the Unicode stream resulting from step 1 into a stream of input 
characters and line terminators (§3.4). 
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3. A translation of the stream of input characters and line terminators resulting 
from step 2 into a sequence of input elements ($3.5) which, after white space 
(§3.6) and comments (§3.7) are discarded, comprise the tokens (§3.5) that are 
the terminal symbols of the syntactic grammar (§2.3). 


The longest possible translation is used at each step, even if the result does not 
ultimately make a correct program while another lexical translation would. There 
is one exception: if lexical translation occurs in a type context (§4.11) and the 
input stream has two or more consecutive > characters that are followed by a non-> 
character, then each > character must be translated to the token for the numerical 
comparison operator >. 


The input characters a--b are tokenized (§3.5) as a, --, b, which is not part of any 
grammatically correct program, even though the tokenization a, -, -, b could be part of a 
grammatically correct program. 


Without the rule for > characters, two consecutive > brackets in a type such as 
List<List<String>> would be tokenized as the signed right shift operator >>, while 
three consecutive > brackets in a type such as List<List<List<String>>> would be 
tokenized as the unsigned right shift operator >>>. Worse, the tokenization of four or more 
consecutive > brackets in a type such as List<List<List<List<String>>>> would be 
ambiguous, as various combinations of >, >>, and >>> tokens could represent the >>>> 
characters. 


3.3 Unicode Escapes 


A compiler for the Java programming language ("Java compiler") first recognizes 
Unicode escapes in its input, translating the ASCII characters \u followed by four 
hexadecimal digits to the UTF-16 code unit (§3.1) for the indicated hexadecimal 
value, and passing all other characters unchanged. Representing supplementary 
characters requires two consecutive Unicode escapes. This translation step results 
in a sequence of Unicode input characters. 


UnicodeInputCharacter: 
UnicodeEscape 
RawInputCharacter 


UnicodeEscape: 
\ UnicodeMarker HexDigit HexDigit HexDigit HexDigit 


UnicodeMarker: 
u fu 
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HexDigit: 
(one of) 


O12345 678 9abecdefABCODE FE 


RawInputCharacter: 
any Unicode character 


The \, u, and hexadecimal digits here are all ASCII characters. 


In addition to the processing implied by the grammar, for each raw input character 
that is a backslash \, input processing must consider how many other \ characters 
contiguously precede it, separating it from a non-\ character or the start of the input 
stream. If this number is even, then the \ is eligible to begin a Unicode escape; if 
the number is odd, then the \ is not eligible to begin a Unicode escape. 


For example, the raw input "\\u2122=\u2122" results in the eleven characters" \ \ u 
212 2 = ™ "(\u2122 is the Unicode encoding of the character ™). 


If an eligible \ is not followed by u, then it is treated as a RawInputCharacter and 
remains part of the escaped Unicode stream. 


If an eligible \ is followed by u, or more than one u, and the last u is not followed 
by four hexadecimal digits, then a compile-time error occurs. 


The character produced by a Unicode escape does not participate in further Unicode 
escapes. 


For example, the raw input \u005cu005a results in the six characters \ u 0 0 5 a, 
because 005c is the Unicode value for \. It does not result in the character Z, which is 
Unicode character 005a, because the \ that resulted from the \u005c is not interpreted as 
the start of a further Unicode escape. 


The Java programming language specifies a standard way of transforming a 
program written in Unicode into ASCII that changes a program into a form that 
can be processed by ASCII-based tools. The transformation involves converting 
any Unicode escapes in the source text of the program to ASCII by adding an extra 
u - for example, \uxxxx becomes \uuxxxx - while simultaneously converting non- 
ASCII characters in the source text to Unicode escapes containing a single u each. 


This transformed version is equally acceptable to a Java compiler and represents 
the exact same program. The exact Unicode source can later be restored from this 
ASCII form by converting each escape sequence where multiple u's are present to a 
sequence of Unicode characters with one fewer u, while simultaneously converting 
each escape sequence with a single u to the corresponding single Unicode character. 
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A Java compiler should use the \uxxxx notation as an output format to display Unicode 
characters when a suitable font is not available. 


3.4 Line Terminators 


A Java compiler next divides the sequence of Unicode input characters into lines 
by recognizing line terminators. 


LineTerminator: 
the ASCII LF character, also known as "newline" 
the ASCII CR character, also known as "return" 
the ASCII CR character followed by the ASCII LF character 


InputCharacter: 
UnicodeInputCharacter but not CR or LF 


Lines are terminated by the ASCII characters CR, or LF, or CR LF. The two 
characters CR immediately followed by LF are counted as one line terminator, not 
two. 


A line terminator specifies the termination of the // form of a comment (§3.7). 


The lines defined by line terminators may determine the line numbers produced by a Java 
compiler. 


The result is a sequence of line terminators and input characters, which are the 
terminal symbols for the third step in the tokenization process. 


3.5 Input Elements and Tokens 


The input characters and line terminators that result from escape processing (§3.3) 
and then input line recognition (§3.4) are reduced to a sequence of input elements. 


Input: 
{InputElement} [Sub] 


InputElement: 
WhiteSpace 
Comment 
Token 
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Token: 
Identifier 
Keyword 
Literal 
Separator 
Operator 


Sub: 
the ASCII SUB character, also known as "control-Z" 


Those input elements that are not white space or comments are tokens. The tokens 
are the terminal symbols of the syntactic grammar (§2.3). 


White space (§3.6) and comments (§3.7) can serve to separate tokens that, if 
adjacent, might be tokenized in another manner. For example, the ASCII characters 
- and = in the input can form the operator token -= ($3.12) only if there is no 
intervening white space or comment. 


AS a special concession for compatibility with certain operating systems, the ASCII 
SUB character (\u001a, or control-Z) is ignored if it is the last character in the 
escaped input stream. 


Consider two tokens x and y in the resulting input stream. If x precedes y, then we 
say that x is to the left of y and that y is to the right of x. 


For example, in this simple piece of code: 


class Empty { 
} 


we say that the } token is to the right of the { token, even though it appears, in this two- 
dimensional representation, downward and to the left of the { token. This convention about 
the use of the words left and right allows us to speak, for example, of the right-hand operand 
of a binary operator or of the left-hand side of an assignment. 


3.6 White Space 


White space is defined as the ASCII space character, horizontal tab character, form 
feed character, and line terminator characters (§3.4). 
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WhiteSpace: 
the ASCII SP character, also known as "space" 
the ASCII HT character, also known as "horizontal tab" 
the ASCII FF character, also known as "form feed" 
LineTerminator 


3.7 Comments 


There are two kinds of comments: 
© /* text */ 


A traditional comment: all the text from the ASCII characters /* to the ASCII 
characters */ is ignored (as in C and C++). 


© // text 


An end-of-line comment: all the text from the ASCII characters // to the end of 
the line is ignored (as in C++). 


Comment: 
TraditionalComment 
EndOfLineComment 


TraditionalComment: 
/ * CommentTail 


CommentTail: 
* CommentTailStar 
NotStar CommentTail 


CommentTailStar: 
/ 
* CommentTailStar 
NotStarNotSlash CommentTail 


NotStar: 
InputCharacter but not * 
LineTerminator 
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NotStarNotSlash: 
InputCharacter but not * or / 
LineTerminator 


EndOfLineComment: 
/ / {InputCharacter} 


These productions imply all of the following properties: 
¢ Comments do not nest. 
e /* and «/ have no special meaning in comments that begin with //. 
e // has no special meaning in comments that begin with /* or /**. 
As a result, the following text is a single complete comment: 
/* this comment /* // /** ends here: */ 


The lexical grammar implies that comments do not occur within character literals 
(§3.10.4) or string literals (§3.10.5). 


3.8 Identifiers 


An identifier is an unlimited-length sequence of Java letters and Java digits, the 
first of which must be a Java letter. 


Identifier: 
IdentifierChars but not a Keyword or BooleanLiteral or NullLiteral 


IdentifierChars: 
JavaLetter {JavaLetterOrDigit} 


JavaLetter: 
any Unicode character that is a "Java letter" 


JavaLetterOrDigit: 
any Unicode character that is a "Java letter-or-digit" 


A "Java letter" is a character for which the method 
Character.isJavaldentifierStart (int) returns true. 
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A "Java letter-or-digit" is a character for which the method 
Character.isJavaldentifierPart (int) returns true. 


The "Java letters" include uppercase and lowercase ASCII Latin letters A-z (\u0041- 
\u005a), and a-z (\u0061-\u007a), and, for historical reasons, the ASCII dollar sign 
(S$, or \u0024) and underscore (_, or \u005f). The dollar sign should be used only in 
mechanically generated source code or, rarely, to access pre-existing names on legacy 
systems. The underscore may be used in identifiers formed of two or more characters, but 
it cannot be used as a one-character identifier due to being a keyword. 


The "Java digits" include the ASCII digits 0-9 (\u0030-\u0039). 


Letters and digits may be drawn from the entire Unicode character set, which 
supports most writing scripts in use in the world today, including the large sets for 
Chinese, Japanese, and Korean. This allows programmers to use identifiers in their 
programs that are written in their native languages. 


An identifier cannot have the same spelling (Unicode character sequence) as a 
keyword (§3.9), boolean literal (§3.10.3), or the null literal ($3.10.7), or a compile- 
time error occurs. 


Two identifiers are the same only if, after ignoring characters that are 
ignorable, the identifiers have the same Unicode character for each letter 
or digit. An ignorable character is a character for which the method 
Character.isIdentifierIgnorable (int) returns true. Identifiers that have the 
same external appearance may yet be different. 


For example, the identifiers consisting of the single letters LATIN CAPITAL LETTER 
A (A, \u0041), LATIN SMALL LETTER A (a, \u0061), GREEK CAPITAL 
LETTER ALPHA (a, \u0391), CYRILLIC SMALL LETTER A (a, \u0430) and 
MATHEMATICAL BOLD ITALIC SMALL A (a, \ud835\udc82) are all different. 


Unicode composite characters are different from their canonical equivalent decomposed 
characters. For example, a LATIN CAPITAL LETTER A ACUTE (A, \u00c1) is different 
from a LATIN CAPITAL LETTER A (a, \u0041) immediately followed by a NON- 
SPACING ACUTE (’, \u0301) in identifiers. See The Unicode Standard, Section 3.11 
"Normalization Forms". 


Examples of identifiers are: 
* String 
* 13 


OpeTny 
° MAX _VALUE 


° isLetterOrDigit 
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A type identifier is an identifier that is not the character sequence var. 


Typeldentifier: 
Identifier but not var 


Type identifiers are used in certain contexts involving the declaration or use of types. For 
example, the name of a class must be a Typeldentifier, so it is illegal to declare a class 


named var (§8.1) 


3.9 Keywords 


51 character sequences, formed from ASCII letters, are reserved for use as 


keywords and cannot be used as identifiers (§3.8). 


Keyword: 
(one of) 
abstract continue 
assert default 
boolean do 
break double 
byte else 
case enum 
catch extends 
char final 
class finally 
const float 

(underscore) 


The keywords const and goto are reserved, even though they are not currently used. 
This may allow a Java compiler to produce better error messages if these C++ keywords 


incorrectly appear in programs. 


for 

at 

goto 
implements 
import 
instanceof 
int 
interface 
long 


native 


new 
package 
private 
protected 
public 
return 
short 
static 
strictfp 


super 


switch 


synchronized 


this 
throw 
throws 
transient 
try 

void 
volatile 


while 


A variety of character sequences are sometimes assumed, incorrectly, to be keywords: 


* true and false are not keywords, but rather boolean literals (§3.10.3). 


* null is not a keyword, but rather the null literal (§3.10.7). 


* var is not a keyword, but rather an identifier with special meaning as the type of a 
local variable declaration (§14.4, §14.14.1, §14.14.2, §14.20.3) and the type of a lambda 


formal parameter (§15.27.1). 
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A further ten character sequences are restricted keywords: open, module, 
requires, transitive, exports, opens, to, uses, provides, and with. These 
character sequences are tokenized as keywords solely where they appear as 
terminals in the ModuleDeclaration, ModuleDirective, and RequiresModifier 
productions (§7.7). They are tokenized as identifiers everywhere else, for 
compatibility with programs written before the introduction of restricted keywords. 
There is one exception: immediately to the right of the character sequence 
requires in the ModuleDirective production, the character sequence transitive 
is tokenized as a keyword unless it is followed by a separator, in which case it is 
tokenized as an identifier. 


3.10 Literals 


A literal is the source code representation of a value of a primitive type ($4.2), the 
String type (§4.3.3), or the null type (§4.1). 


Literal: 
IntegerLiteral 
FloatingPointLiteral 
BooleanLiteral 
CharacterLiteral 
StringLiteral 
NullLiteral 


3.10.1 Integer Literals 


An integer literal may be expressed in decimal (base 10), hexadecimal (base 16), 
octal (base 8), or binary (base 2). 


IntegerLiteral: 
DecimalIntegerLiteral 
HexIntegerLiteral 
OctalIntegerLiteral 
BinaryIntegerLiteral 


DecimalIntegerLiteral: 
DecimalNumeral [IntegerTypeSuffix] 


HexIntegerLiteral: 
HexNumeral [IntegerTypeSuffix] 


3.10 


25 


3.10 Literals LEXICAL STRUCTURE 


OctalIntegerLiteral: 
OctalNumeral [IntegerTypeSuffix] 


BinaryIntegerLiteral: 
BinaryNumeral [IntegerTypeSuffix] 


IntegerTypeSuffix: 
(one of) 


1L 


An integer literal is of type long if it is suffixed with an ASCTI letter 1 or 1 (ell); 
otherwise it is of type int (§4.2.1). 


The suffix L is preferred, because the letter 1 (ell) is often hard to distinguish from the digit 
1 (one). 


Underscores are allowed as separators between digits that denote the integer. 


In a hexadecimal or binary literal, the integer is only denoted by the digits after 
the 0x or 0b characters and before any type suffix. Therefore, underscores may not 
appear immediately after ox or Ob, or after the last digit in the numeral. 


In a decimal or octal literal, the integer is denoted by all the digits in the literal 
before any type suffix. Therefore, underscores may not appear before the first digit 
or after the last digit in the numeral. Underscores may appear after the initial 0 in 
an octal numeral (since 0 is a digit that denotes part of the integer) and after the 
initial non-zero digit in a non-zero decimal literal. 
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A decimal numeral is either the single ASCII digit 0, representing the integer zero, 
or consists of an ASCII digit from 1 to 9 optionally followed by one or more ASCII 
digits from 0 to 9 interspersed with underscores, representing a positive integer. 


DecimalNumeral: 
0) 
NonZeroDigit [Digits] 
NonZeroDigit Underscores Digits 


NonZeroDigit: 
(one of) 


12345678 9 


Digits: 

Digit 

Digit [DigitsAndUnderscores] Digit 
Digit: 

0 

NonZeroDigit 


DigitsAndUnderscores: 
DigitOrUnderscore {DigitOrUnderscore} 


DigitOrUnderscore: 
Digit 


Underscores: 


Bay fe 
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A hexadecimal numeral consists of the leading ASCH characters 0x or ox followed 
by one or more ASCII hexadecimal digits interspersed with underscores, and can 
represent a positive, zero, or negative integer. 


Hexadecimal digits with values 10 through 15 are represented by the ASCII letters 
a through ¢£ or a through F, respectively; each letter used as a hexadecimal digit 
may be uppercase or lowercase. 


HexNumeral: 
0 x HexDigits 
0 x HexDigits 


HexDigits: 
HexDigit 
HexDigit [HexDigitsAndUnderscores] HexDigit 


HexDigit: 
(one of) 


012345678 9abcde fABCODEF 


HexDigitsAndUnderscores: 
HexDigitOrUnderscore {HexDigitOrUnderscore} 


HexDigitOrUnderscore: 
HexDigit 


The HexDigit production above comes from §3.3. 
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An octal numeral consists of an ASCII digit 0 followed by one or more of the ASCII 
digits 0 through 7 interspersed with underscores, and can represent a positive, zero, 
or negative integer. 


OctalNumeral: 
0 OctalDigits 
0 Underscores OctalDigits 


OctalDigits: 
OctalDigit 
OctalDigit [OctalDigitsAndUnderscores] OctalDigit 


OctalDigit: 
(one of) 


01234567 


OctalDigitsAndUnderscores: 
OctalDigitOrUnderscore {OctalDigitOrUnderscore} 


OctalDigitOrUnderscore: 
OctalDigit 


Note that octal numerals always consist of two or more digits, as 0 alone is always 
considered to be a decimal numeral - not that it matters much in practice, for the numerals 
0, 00, and 0x0 all represent exactly the same integer value. 
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A binary numeral consists of the leading ASCII characters 0b or 08 followed by one 
or more of the ASCII digits 0 or 1 interspersed with underscores, and can represent 
a positive, zero, or negative integer. 


BinaryNumeral: 
0 b BinaryDigits 
0 B BinaryDigits 


BinaryDigits: 
BinaryDigit 
BinaryDigit [BinaryDigitsAndUnderscores] BinaryDigit 


BinaryDigit: 
(one of) 


Ol 


BinaryDigitsAndUnderscores: 
BinaryDigitOrUnderscore {BinaryDigitOrUnderscore} 


BinaryDigitOrUnderscore: 
BinaryDigit 
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The largest decimal literal of type int is 2147483648 Oy 


All decimal literals from 0 to 2147483647 may appear anywhere an int literal may 
appear. The decimal literal 2147483648 may appear only as the operand of the 
unary minus operator - (§15.15.4). 


It is a compile-time error if the decimal literal 2147483648 appears anywhere other 
than as the operand of the unary minus operator; or if a decimal literal of type int 
is larger than 2147483648 (2°!). 


The largest positive hexadecimal, octal, and gue literals of type int - each of 
which represents the decimal value 2147483647 (2 1) - are respectively: 


* Ox7£ff£_ffff, 
¢ 0177_7777_7777, and 


© 060111 TAT APT de es ed 


The most negative hexadecimal, octal, and binary literals of type int - each of 
which represents the decimal value -2147483648 (97) - are respectively: 


* 0x8000_0000, 
* 0200_0000_0000, and 


* 0b1000_0000_0000_0000_0000_0000_0000_0000 


The following hexadecimal, octal, and binary literals represent the decimal value 
-1: 


°* Oxffff_ffff, 
* 0377_7777_7777, and 


© -0b1 99-7 2400 TUT 1d a TD OT 


It is a compile-time error if a hexadecimal, octal, or binary int literal does not fit 
in 32 bits. 


The largest decimal literal of type long is 9223372036854775808L Oy, 


All decimal literals from 0L to 9223372036854775807L may appear anywhere a 
long literal may appear. The decimal literal 9223372036854775808L may appear 
only as the operand of the unary minus operator - (§15.15.4). 


It is a compile-time error if the decimal literal 9223372036854775808L appears 
anywhere other than as the operand of the unary minus operator; or if a decimal 
literal of type Long is larger than 9223372036854775808L >), 
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The largest positive hexadecimal, octal, and binary literals of type long - each 
of which represents the decimal value 9223372036854775807L OP) - are 
respectively: 


° Ox7fff_ffff_ffff_ffftf1, 


© 07_7777_7777_7777_7777_7777L, and 


e@ ObOLL LTT Ava, Pa Ta ET TI 


The most negative hexadecimal, octal, and binary literals of type long - each 
of which represents the decimal value -9223372036854775808L EO) - are 
respectively: 


* 0x8000_0000_0000_0000L, and 


* 010_0000_0000_0000_0000_0000L, and 


e 0b1000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000L 


The following hexadecimal, octal, and binary literals represent the decimal value 
-1L: 


° Oxffff_ffff_ffff_ffff1, 


© 017_7777_7777_7777_7777_7777L, and 


@ ObLILL 1117 Td1 1 ad VI1a A Pa TIT ed 1 aad ae a 


It is a compile-time error if a hexadecimal, octal, or binary long literal does not 
fit in 64 bits. 


Examples of int literals: 
0 2 0372 OxDada_Cafe 1996 0x00_FF__00_FF 
Examples of long literals: 


Ol 0777L 0x100000000L 2_147_483_648L OxCOBOL 


3.10.2 Floating-Point Literals 


A floating-point literal has the following parts: a whole-number part, a decimal or 
hexadecimal point (represented by an ASCII period character), a fraction part, an 
exponent, and a type suffix. 


A floating-point literal may be expressed in decimal (base 10) or hexadecimal (base 
16). 
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For decimal floating-point literals, at least one digit (in either the whole number or 
the fraction part) and either a decimal point, an exponent, or a float type suffix are 
required. All other parts are optional. The exponent, if present, is indicated by the 
ASCII letter e or £ followed by an optionally signed integer. 


For hexadecimal floating-point literals, at least one digit is required (in either the 
whole number or the fraction part), and the exponent is mandatory, and the float 
type suffix is optional. The exponent is indicated by the ASCII letter p or P followed 
by an optionally signed integer. 


Underscores are allowed as separators between digits that denote the whole-number 
part, and between digits that denote the fraction part, and between digits that denote 
the exponent. 


FloatingPointLiteral: 
DecimalFloatingPointLiteral 
HexadecimalFloatingPointLiteral 


DecimalFloatingPointLiteral: 
Digits . [Digits] [ExponentPart] [FloatTypeSuffix] 
. Digits [ExponentPart] [FloatTypeSuffix] 
Digits ExponentPart [FloatTypeSuffix] 
Digits [ExponentPart] FloatType Suffix 


ExponentPart: 
ExponentIndicator SignedInteger 


ExponentIndicator: 


(one of) 


eh 


SignedInte ger: 
[Sign] Digits 


Sign: 
(one of) 


+ - 


FloatTypeSuffix: 
(one of) 


fFdaobD 
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HexadecimalFloatingPointLiteral: 
HexSignificand BinaryExponent [FloatTypeSuffix] 


HexSignificand: 
HexNumeral [ .] 
0 x [HexDigits] . HexDigits 
0 x [HexDigits] . HexDigits 


BinaryExponent: 
BinaryExponentIndicator SignedInteger 


BinaryExponentIndicator: 


(one of) 


pP 


A floating-point literal is of type float if it is suffixed with an ASCII letter F or £; 
otherwise its type is double and it can optionally be suffixed with an ASCII letter 
D or d (§4.2.3). 


The elements of the types float and double are those values that can be 
represented using the IEEE 754 32-bit single-precision and 64-bit double-precision 
binary floating-point formats, respectively. 


The details of proper input conversion from a Unicode string representation of a floating- 
point number to the internal IEEE 754 binary floating-point representation are described 
for the methods valueoOf of class Float and class Double of the package java.lang. 


The largest positive finite literal of type float is 3.4028235e38f. 

The smallest positive finite non-zero literal of type float is 1.40e-45£. 

The largest positive finite literal of type double is 1.7976931348623157e308. 
The smallest positive finite non-zero literal of type double is 4. 9e-324. 


It is a compile-time error if a non-zero floating-point literal is too large, so that on 
rounded conversion to its internal representation, it becomes an IEEE 754 infinity. 


A program can represent infinities without producing a compile-time error by using 
constant expressions such as 1£/0f or -1d/0d or by using the predefined constants 
POSITIVE_INFINITyY and NEGATIVE_INFINITY of the classes Float and Double. 


It is a compile-time error if a non-zero floating-point literal is too small, so that, on 
rounded conversion to its internal representation, it becomes a zero. 
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A compile-time error does not occur if a non-zero floating-point literal has a small 
value that, on rounded conversion to its internal representation, becomes a non- 
zero denormalized number. 


Predefined constants representing Not-a-Number values are defined in the classes 
Float and Double as Float .NaN and Double.NaN. 


Examples of float literals: 
lelf 2.f at Of 3.14f 6.022137e+23£ 
Examples of doub1e literals: 


lel 2. iad 0.0 3.14 le-9d Lela 


3.10.3. Boolean Literals 


The boolean type has two values, represented by the boolean literals true and 
false, formed from ASCII letters. 


BooleanLiteral: 


(one of) 


true false 


A boolean literal is always of type boolean (§4.2.5). 


3.10.4 Character Literals 


A character literal is expressed as a character or an escape sequence (§3.10.6), 
enclosed in ASCII single quotes. (The single-quote, or apostrophe, character is 
\u0027.) 


CharacterLiteral: 
' SingleCharacter ' 
' EscapeSequence ' 


SingleCharacter: 
InputCharacter but not ' or \ 


See §3.10.6 for the definition of EscapeSequence. 


Character literals can only represent UTF-16 code units ($3.1), i.e., they are limited 
to values from \u0000 to \ufff£. Supplementary characters must be represented 
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either as a surrogate pair within a char sequence, or as an integer, depending on 
the API they are used with. 


A character literal is always of type char (§4.2.1). 


It is a compile-time error for the character following the SingleCharacter or 
EscapeSequence to be other than a '. 


It is a compile-time error for a line terminator (§3.4) to appear after the opening 
' and before the closing '. 


As specified in §3.4, the characters CR and LF are never an InputCharacter; each is 
recognized as constituting a LineTerminator. 


The following are examples of char literals: 


e ota 
e met 

e \t! 

e o\\t 
emt 

* '\u03a9' 
° '\UFFFF! 
oI NTT 

. vm 


Because Unicode escapes are processed very early, it is not correct to write '\u000a' 
for a character literal whose value is linefeed (LF); the Unicode escape \u000a is 
transformed into an actual linefeed in translation step 1 (§3.3) and the linefeed becomes a 
LineTerminator in step 2 (§3.4), and so the character literal is not valid in step 3. Instead, 
one should use the escape sequence '\n' (§3.10.6). Similarly, it is not correct to write 
"\u000d' for a character literal whose value is carriage return (CR). Instead, use '\r'. 


In C and C++, a character literal may contain representations of more than one character, 
but the value of such a character literal is implementation-defined. In the Java programming 
language, a character literal always represents exactly one character. 


3.10.5 String Literals 


A string literal consists of zero or more characters enclosed in double quotes. 
Characters may be represented by escape sequences (§3.10.6) - one escape 
sequence for characters in the range U+0000 to U+FFFF, two escape sequences 
for the UTF-16 surrogate code units of characters in the range U+010000 to U 
+10FFFF. 
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StringLiteral: 
" {StringCharacter} ™ 


String Character: 
InputCharacter but not " or \ 
EscapeSequence 


See §3.10.6 for the definition of EscapeSequence. 


A string literal is always of type string (§4.3.3). 


It is a compile-time error for a line terminator to appear after the opening " and 
before the closing matching ". 


As specified in §3.4, the characters CR and LF are never an InputCharacter; each is 
recognized as constituting a LineTerminator. 


A long string literal can always be broken up into shorter pieces and written as a (possibly 
parenthesized) expression using the string concatenation operator + (§15.18.1). 


The following are examples of string literals: 


// the empty string 


ey // a string containing " alone 

"This is a string" // a string containing 16 characters 

"This! sis) are // actually a string-valued constant expression, 
"two-line string" // formed from two string literals 


Because Unicode escapes are processed very early, it is not correct to write "\u000a" 
for a string literal containing a single linefeed (LF); the Unicode escape \u000a is 
transformed into an actual linefeed in translation step 1 (§3.3) and the linefeed becomes 
a LineTerminator in step 2 (§3.4), and so the string literal is not valid in step 3. Instead, 
one should write "\n" (§3.10.6). Similarly, it is not correct to write "\u000d" for a string 
literal containing a single carriage return (CR). Instead, use "\r". Finally, it is not possible 
to write "\u0022" for a string literal containing a double quotation mark ("). 


A String literal is a reference to an instance of class st ring (§4.3.1, §4.3.3). 


Moreover, a string literal always refers to the same instance of class string. This 
is because string literals - or, more generally, strings that are the values of constant 
expressions (§15.28) - are "interned" so as to share unique instances, using the 
method String.intern (§12.5). 


Example 3.10.5-1. String Literals 
The program consisting of the compilation unit (§7.3): 


package testPackage; 
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class Test { 
public static void main(String[] args) { 


String hello = "Hello", lo = "lo"; 
System.out.println(hello == "Hello"); 
System.out.println(Other.hello == hello); 
System.out.println(other.Other.hello == hello); 
System.out.println(hello == ("Hel"+"lo")); 
System.out.println(hello == ("Hel"+lo)); 
System.out.println(hello == ("Hel"+lo) .intern()); 
} 
} 
class Other { static String hello = "Hello"; } 


and the compilation unit: 


package other; 
public class Other { public static String hello = "Hello"; } 


produces the output: 


true 
true 
true 
true 
false 
true 


This example illustrates six points: 
¢ String literals in the same class and package represent references to the same String 


object (§4.3.1). 


¢ String literals in different classes in the same package represent references to the same 
String object. 


¢ String literals in different classes in different packages likewise represent references to 
the same St ring object. 


¢ Strings concatenated from constant expressions (§15.28) are computed at compile time 
and then treated as if they were literals. 


¢ Strings computed by concatenation at run time are newly created and therefore distinct. 


¢ The result of explicitly interning a computed string is the same String object as any 
pre-existing string literal with the same contents. 


3.10.6 Escape Sequences for Character and String Literals 


The character and string escape sequences allow for the representation of some 
nongraphic characters without using Unicode escapes, as well as the single quote, 
double quote, and backslash characters, in character literals (§3.10.4) and string 
literals (§3.10.5). 
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EscapeSequence: 
\ b (backspace BS, Unicode \u0008) 
t (horizontal tab HT, Unicode \u0009) 
n_ (linefeed LF, Unicode \u000a) 
f£ (form feed FF, Unicode \u000c) 
r (carriage return CR, Unicode \u000d) 
"(double quote ", Unicode \u0022) 
' (single quote ', Unicode \u0027) 
\ (backslash \, Unicode \u005c) 
OctalEscape (octal value, Unicode \u0000 to \uo0f£) 


PO OY GO gO gh 


OctalEscape: 
\ OctalDigit 
\ OctalDigit OctalDigit 
\ ZeroToThree OctalDigit OctalDigit 


OctalDigit: 
(one of) 


OZ. 3 496 7 


ZeroTothree: 
(one of) 


Ob r2s3 
The OctalDigit production above comes from §3.10.1. 


It is a compile-time error if the character following a backslash in an escape 
sequence is not an ASCII b, t, n, f, r, ", ', \, 0, 1, 2, 3, 4, 5, 6, or 7. The Unicode 
escape \u is processed earlier (§3.3). 


Octal escapes are provided for compatibility with C, but can express only Unicode values 
\u0000 through \u00FF, so Unicode escapes are usually preferred. 


3.10.7 The Null Literal 


The null type has one value, the null reference, represented by the null literal null, 
which is formed from ASCII characters. 


NullLiteral: 
null 


A null literal is always of the null type (§4.1). 


39 


3.11 


40 


Separators 


3.11 Separators 


Twelve tokens, formed from ASCII characters, are the separators (punctuators). 


Separator: 


(one of) 
( ) { } [ ] ; ' . Jide @ 


3.12 Operators 


38 tokens, formed from ASCII characters, are the operators. 


Operator: 
(one of) 
= > < ! ~  ? : -> 
> < ! && | te f= 
- * / | a % << >> >>> 
* ve | . & << >> >>> 
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CHAPTER | 


Types, Values, and Variables 


Tue Java programming language is a statically typed language, which means 
that every variable and every expression has a type that is known at compile time. 


The Java programming language is also a strongly typed language, because types 
limit the values that a variable ($4.12) can hold or that an expression can produce, 
limit the operations supported on those values, and determine the meaning of the 
operations. Strong static typing helps detect errors at compile time. 


The types of the Java programming language are divided into two categories: 
primitive types and reference types. The primitive types ($4.2) are the boolean 
type and the numeric types. The numeric types are the integral types byte, short, 
int, long, and char, and the floating-point types float and double. The reference 
types (§4.3) are class types, interface types, and array types. There is also a special 
null type. An object (§4.3.1) is a dynamically created instance of a class type or a 
dynamically created array. The values of a reference type are references to objects. 
All objects, including arrays, support the methods of class object ($4.3.2). String 
literals are represented by st ring objects (§4.3.3). 


4.1 The Kinds of Types and Values 


There are two kinds of types in the Java programming language: primitive types 
($4.2) and reference types (§4.3). There are, correspondingly, two kinds of data 
values that can be stored in variables, passed as arguments, returned by methods, 
and operated on: primitive values (§4.2) and reference values (§4.3). 


Type: 
PrimitiveType 
ReferenceType 
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There is also a special null type, the type of the expression nu11 (§3.10.7, §15.8.1), 
which has no name. 


Because the null type has no name, it is impossible to declare a variable of the null 
type or to cast to the null type. 


The null reference is the only possible value of an expression of null type. 
The null reference can always be assigned or cast to any reference type (§5.2, $5.3, 


§5.5). 


In practice, the programmer can ignore the null type and just pretend that null is merely 
a special literal that can be of any reference type. 


4.2 Primitive Types and Values 


A primitive type is predefined by the Java programming language and named by 
its reserved keyword (§3.9): 


PrimitiveType: 
{Annotation} NumericType 
{Annotation} boolean 


NumericType: 
IntegralType 
FloatingPointType 


IntegralType: 
(one of) 


byte short int long char 


FloatingPointType: 
(one of) 


float double 


Primitive values do not share state with other primitive values. 
The numeric types are the integral types and the floating-point types. 


The integral types are byte, short, int, and long, whose values are 8-bit, 16-bit, 
32-bit and 64-bit signed two's-complement integers, respectively, and char, whose 
values are 16-bit unsigned integers representing UTF-16 code units (§3.1). 
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The floating-point types are float, whose values include the 32-bit IEEE 754 
floating-point numbers, and double, whose values include the 64-bit IEEE 754 
floating-point numbers. 


The boolean type has exactly two values: true and false. 


4.2.1 Integral Types and Values 


The values of the integral types are integers in the following ranges: 

¢ For byte, from -128 to 127, inclusive 

¢ For short, from -32768 to 32767, inclusive 

¢ For int, from -2147483648 to 2147483647, inclusive 

¢ For long, from -9223372036854775808 to 9223372036854775807, inclusive 


¢ For char, from '\u0000' to '\ufffFf' inclusive, that is, from 0 to 65535 


4.2.2 Integer Operations 


The Java programming language provides a number of operators that act on integral 
values: 


¢ The comparison operators, which result in a value of type boolean: 
— The numerical comparison operators <, <=, >, and >= (§15.20.1) 
— The numerical equality operators == and != (§15.21.1) 
¢ The numerical operators, which result in a value of type int or long: 
— The unary plus and minus operators + and - (§15.15.3, §15.15.4) 
— The multiplicative operators *, /, and % ($15.17) 
— The additive operators + and - (§15.18) 
— The increment operator ++, both prefix (§15.15.1) and postfix (§15.14.2) 
— The decrement operator --, both prefix (§15.15.2) and postfix (§15.14.3) 
— The signed and unsigned shift operators <<, >>, and >>> ($15.19) 
— The bitwise complement operator ~ (§15.15.5) 
— The integer bitwise operators «, *, and | (§15.22.1) 
¢ The conditional operator ? : ($15.25) 
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¢ The cast operator ($15.16), which can convert from an integral value to a value 
of any specified numeric type 


¢ The string concatenation operator + (§15.18.1), which, when given a string 
operand and an integral operand, will convert the integral operand to a String 
(the decimal form of a byte, short, int, or long operand, or the character 
of a char operand), and then produce a newly created string that is the 
concatenation of the two strings 


Other useful constructors, methods, and constants are predefined in the classes 
Byte, Short, Integer, Long, and Character. 


If an integer operator other than a shift operator has at least one operand of type 
long, then the operation is carried out using 64-bit precision, and the result of 
the numerical operator is of type long. If the other operand is not Long, it is first 
widened (§5.1.5) to type long by numeric promotion (§5.6). 


Otherwise, the operation is carried out using 32-bit precision, and the result of the 
numerical operator is of type int. If either operand is not an int, it is first widened 
to type int by numeric promotion. 


Any value of any integral type may be cast to or from any numeric type. There are 
no casts between integral types and the type boolean. 


See §4.2.5 for an idiom to convert integer expressions to boolean. 


The integer operators do not indicate overflow or underflow in any way. 


An integer operator can throw an exception (§11 (Exceptions)) for the following 
reasons: 


e Any integer operator can throw a NullPointerException if unboxing 
conversion (§5.1.8) of a null reference is required. 


¢ The integer divide operator / (§15.17.2) and the integer remainder operator % 
($15.17.3) can throw an Arithmet icException if the right-hand operand is zero. 


e The increment and decrement operators ++ (§15.14.2, §15.15.1) and -- 
(§15.14.3, §15.15.2) can throw an outofMemoryError if boxing conversion 
($5.1.7) is required and there is not sufficient memory available to perform the 
conversion. 


Example 4.2.2-1. Integer Operations 


class Test { 
public static void main(String[] args) { 
int i = 1000000; 
System.out.println(i * i); 
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long 1 = i; 
System.out.println(l * 1); 
System.out.print1n(20296 / (1 - i)); 


} 
This program produces the output: 


-727379968 
1000000000000 


and then encounters an ArithmeticException in the division by 1 - i, because 1 
- iis zero. The first multiplication is performed in 32-bit precision, whereas the second 
multiplication is a long multiplication. The value -727379968 is the decimal value of the 
low 32 bits of the mathematical result, 1000000000000, which is a value too large for 
type int. 


4.2.3 Floating-Point Types, Formats, and Values 


The floating-point types are float and double, which are conceptually associated 
with the single-precision 32-bit and double-precision 64-bit format IEEE 754 
values and operations as specified in IEEE Standard for Binary Floating-Point 
Arithmetic, ANSI/TEEE Standard 754-1985 (IEEE, New York). 


The IEEE 754 standard includes not only positive and negative numbers that consist 
of a sign and magnitude, but also positive and negative zeros, positive and negative 
infinities, and special Not-a-Number values (hereafter abbreviated NaN). A NaN 
value is used to represent the result of certain invalid operations such as dividing 
zero by zero. NaN constants of both float and double type are predefined as 
Float .NaN and Double.NaN. 


Every implementation of the Java programming language is required to support two 
standard sets of floating-point values, called the float value set and the double value 
set. In addition, an implementation of the Java programming language may support 
either or both of two extended-exponent floating-point value sets, called the float- 
extended-exponent value set and the double-extended-exponent value set. These 
extended-exponent value sets may, under certain circumstances, be used instead 
of the standard value sets to represent the values of expressions of type float or 
double (§5.1.13, §15.4). 


The finite nonzero values of any floating-point value set can all be expressed in 
the form s-m-2°°%*)). where s is +1 or -1, mis a positive integer less than 
vie and e is an integer between Ejnin = OED) and Ejnax = gM, inclusive, and 
where N and K are parameters that depend on the value set. Some values can 
be represented in this form in more than one way; for example, supposing that a 
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value v in a value set might be represented in this form using certain values for 
s, m, and e, then if it happened that m were even and e were less than oe one 
could halve m and increase e by | to produce a second representation for the same 
value v. A representation in this form is called normalized if m = 21. otherwise 
the representation is said to be denormalized. If a value in a value set cannot be 
represented in such a way that m= 2"! then the value is said to be a denormalized 
value, because it has no normalized representation. 


The constraints on the parameters N and K (and on the derived parameters Ejnin 
and Emax) for the two required and two optional floating-point value sets are 
summarized in Table 4.2.3-A. 


Table 4.2.3-A. Floating-point value set parameters 


Parameter float float-extended- double double-extended- 
exponent exponent 

N 24 24 53 53 

K 8 ii " 215 

Emax +127 > +1023 +1023 > +16383 

Emin -126 < -1022 -1022 < -16382 


Where one or both extended-exponent value sets are supported by an 
implementation, then for each supported extended-exponent value set there is 
a specific implementation-dependent constant K, whose value is constrained by 
Table 4.2.3-A; this value K in turn dictates the values for E,,j, and Enay- 


Each of the four value sets includes not only the finite nonzero values that are 
ascribed to it above, but also NaN values and the four values positive zero, negative 
zero, positive infinity, and negative infinity. 


Note that the constraints in Table 4.2.3-A are designed so that every element of the 
float value set is necessarily also an element of the float-extended-exponent value 
set, the double value set, and the double-extended-exponent value set. Likewise, 
each element of the double value set is necessarily also an element of the double- 
extended-exponent value set. Each extended-exponent value set has a larger range 
of exponent values than the corresponding standard value set, but does not have 
more precision. 


The elements of the float value set are exactly the values that can be represented 
using the single floating-point format defined in the IEEE 754 standard. The 
elements of the double value set are exactly the values that can be represented using 
the double floating-point format defined in the IEEE 754 standard. Note, however, 
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that the elements of the float-extended-exponent and double-extended-exponent 
value sets defined here do not correspond to the values that can be represented 
using IEEE 754 single extended and double extended formats, respectively. 


The float, float-extended-exponent, double, and double-extended-exponent value 
sets are not types. It is always correct for an implementation of the Java 
programming language to use an element of the float value set to represent a value 
of type float; however, it may be permissible in certain regions of code for an 
implementation to use an element of the float-extended-exponent value set instead. 
Similarly, it is always correct for an implementation to use an element of the double 
value set to represent a value of type double; however, it may be permissible in 
certain regions of code for an implementation to use an element of the double- 
extended-exponent value set instead. 


Except for NaN, floating-point values are ordered; arranged from smallest to 
largest, they are negative infinity, negative finite nonzero values, positive and 
negative zero, positive finite nonzero values, and positive infinity. 


IEEE 754 allows multiple distinct NaN values for each of its single and double 
floating-point formats. While each hardware architecture returns a particular bit 
pattern for NaN when a new NaN is generated, a programmer can also create 
NaNs with different bit patterns to encode, for example, retrospective diagnostic 
information. 


For the most part, the Java SE Platform treats NaN values of a given type as though 
collapsed into a single canonical value, and hence this specification normally refers 
to an arbitrary NaN as though to a canonical value. 


However, version 1.3 of the Java SE Platform introduced methods enabling the 
programmer to distinguish between NaN values: the Float.floatToRawIntBits and 
Double.doubleToRawLongBits methods. The interested reader is referred to the 
specifications for the Float and Double classes for more information. 


Positive zero and negative zero compare equal; thus the result of the expression 
0.0==-0.0 is true and the result of 0.0>-0.0 is false. But other operations can 
distinguish positive and negative zero; for example, 1.0/0.0 has the value positive 
infinity, while the value of 1.0/-0.0 is negative infinity. 


NaN is unordered, so: 


¢ The numerical comparison operators <, <=, >, and >= return false if either or 
both operands are NaN (§15.20.1). 


In particular, (x<y) == ! (x>=y) will be false if x or y is NaN. 


¢ The equality operator == returns false if either operand is NaN. 
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¢ The inequality operator != returns true if either operand is NaN (§15.21.1). 


In particular, x!=x is true if and only if x is NaN. 


4.2.4 Floating-Point Operations 


The Java programming language provides a number of operators that act on 
floating-point values: 


¢ The comparison operators, which result in a value of type boolean: 
— The numerical comparison operators <, <=, >, and >= (§15.20.1) 
— The numerical equality operators == and != (§15.21.1) 
¢ The numerical operators, which result in a value of type float or double: 
— The unary plus and minus operators + and - (§15.15.3, §15.15.4) 
— The multiplicative operators «, /, and % ($15.17) 
— The additive operators + and - (§15.18.2) 
— The increment operator ++, both prefix (§15.15.1) and postfix (§15.14.2) 
— The decrement operator --, both prefix ($15.15.2) and postfix (§15.14.3) 
¢ The conditional operator ? : ($15.25) 


¢ The cast operator ($15.16), which can convert from a floating-point value to a 
value of any specified numeric type 


¢ The string concatenation operator + (§15.18.1), which, when given a string 
operand and a floating-point operand, will convert the floating-point operand to 
a String representing its value in decimal form (without information loss), and 
then produce a newly created st ring by concatenating the two strings 


Other useful constructors, methods, and constants are predefined in the classes 
Float, Double, and Math. 


If at least one of the operands to a binary operator is of floating-point type, then 
the operation is a floating-point operation, even if the other is integral. 


If at least one of the operands to a numerical operator is of type double, then the 
operation is carried out using 64-bit floating-point arithmetic, and the result of the 
numerical operator is a value of type double. If the other operand is not a double, 
it is first widened (§5.1.5) to type double by numeric promotion (§5.6). 
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Otherwise, the operation is carried out using 32-bit floating-point arithmetic, and 
the result of the numerical operator is a value of type float. (If the other operand 
is not a float, it is first widened to type float by numeric promotion.) 


Any value of a floating-point type may be cast to or from any numeric type. There 
are no casts between floating-point types and the type boolean. 


See §4.2.5 for an idiom to convert floating-point expressions to boolean. 


Operators on floating-point numbers behave as specified by IEEE 754 (with 
the exception of the remainder operator (§15.17.3)). In particular, the Java 
programming language requires support of IEEE 754 denormalized floating-point 
numbers and gradual underflow, which make it easier to prove desirable properties 
of particular numerical algorithms. Floating-point operations do not "flush to zero" 
if the calculated result is a denormalized number. 


The Java programming language requires that floating-point arithmetic behave 
as if every floating-point operator rounded its floating-point result to the result 
precision. /nexact results must be rounded to the representable value nearest to the 
infinitely precise result; if the two nearest representable values are equally near, 
the one with its least significant bit zero is chosen. This is the IEEE 754 standard's 
default rounding mode known as round to nearest. 


The Java programming language uses round toward zero when converting a 
floating value to an integer (§5.1.3), which acts, in this case, as though the number 
were truncated, discarding the mantissa bits. Rounding toward zero chooses as its 
result the format's value closest to and no greater in magnitude than the infinitely 
precise result. 


A floating-point operation that overflows produces a signed infinity. 


A floating-point operation that underflows produces a denormalized value or a 
signed zero. 


A floating-point operation that has no mathematically definite result produces NaN. 
All numeric operations with NaN as an operand produce NaN as a result. 


A floating-point operator can throw an exception ($11 (Exceptions)) for the 
following reasons: 


¢ Any floating-point operator can throw a NullPointerException if unboxing 
conversion (§5.1.8) of a null reference is required. 


e The increment and decrement operators ++ (§15.14.2, §15.15.1) and -- 
(§15.14.3, §15.15.2) can throw an outofMemoryError if boxing conversion 
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($5.1.7) is required and there is not sufficient memory available to perform the 
conversion. 


Example 4.2.4-1. Floating-point Operations 


class Test { 
public static void main(String[] args) { 


// An example of overflow: 

double d = 1e308; 

System.out.print ("overflow produces infinity: "); 
System.out.printin(d + "*10==" + d*10); 

// An example of gradual underflow: 

d = le-305 * Math.PI; 


System.out.print ("gradual underflow: "+ d+ "\n LD 
for (int i = 0; i < 4; i++) 
System.out.print(" " + (d /= 100000)); 


System.out.println(); 
// An example of NaN: 
System.out.print ("0.0/0.0 is Not-a-Number: "); 
d = 0.0/0.0; 
System.out.printin(d); 
// An example of inexact results and rounding: 
System.out.print ("inexact results with float:"); 
for (int i = 0; i < 100; i++) { 

float z= 1.0f / i; 

df COR a Se OE) 

System.out.print(" "+ i); 

} 
System.out.println(); 
// Another example of inexact results and rounding: 
System.out.print ("inexact results with double:"); 
for (int i = 0; i < 100; i++) { 

double z= 1.0 / i; 

TE (2 a NS OY 

System.out.print(" " + i); 

} 
System.out.println(); 
// An example of cast to integer rounding: 


System.out.print ("cast to int rounds toward 0: "); 
d = 12345.6; 
System.out.println((int)d + " " + (int) (-d)); 


This program produces the output: 
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overflow produces infinity: 1.0E308*10==Infinity 

gradual underflow: 3.141592653589793E-305 
3.1415926535898E-310 3.141592653E-315 3.142E-320 0.0 

0.0/0.0 is Not-a-Number: NaN 

inexact results with float: 0 41 47 55 61 82 83 94 97 

inexact results with double: 0 49 98 

cast to int rounds toward 0: 12345 -12345 


This example demonstrates, among other things, that gradual underflow can result in a 
gradual loss of precision. 


The results when i is 0 involve division by zero, so that z becomes positive infinity, and 
z * 0 is NaN, which is not equal to 1.0. 


4.2.5 The boolean Type and boolean Values 


The boolean type represents a logical quantity with two possible values, indicated 
by the literals true and false (§3.10.3). 


The boolean operators are: 

e The relational operators == and != (§15.21.2) 

¢ The logical complement operator ! (§15.15.6) 

¢ The logical operators «, *, and | (§15.22.2) 

¢ The conditional-and and conditional-or operators «& ($15.23) and | | ($15.24) 
¢ The conditional operator ? : ($15.25) 


¢ The string concatenation operator + (§15.18.1), which, when given a string 
operand and a boolean operand, will convert the boolean operand to a String 
(either "true" or "false"), and then produce a newly created st ring that is the 
concatenation of the two strings 


Boolean expressions determine the control flow in several kinds of statements: 
e The if statement (§14.9) 

¢ The while statement ($14.12) 

e The do statement (§14.13) 

¢ The for statement ($14.14) 


A boolean expression also determines which subexpression is evaluated in the 
conditional ?_ : operator ($15.25). 


Only boolean and Boolean expressions can be used in control flow statements and 
as the first operand of the conditional operator ? 
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An integer or floating-point expression x can be converted to a boolean value, 
following the C language convention that any nonzero value is true, by the 
expression x!=0. 


An object reference obj can be converted to a boolean value, following the C 
language convention that any reference other than nu11 is true, by the expression 
obj!=null. 


A boolean value can be converted to a String by string conversion (§5.4). 


A boolean value may be cast to type boolean, Boolean, or Object (§5.5). No other 
casts on type boolean are allowed. 


4.3 Reference Types and Values 


There are four kinds of reference types: class types (§8.1), interface types ($9.1), 
type variables (§4.4), and array types (§10.1). 


ReferenceType: 
ClassOrInterfaceType 
TypeVariable 
ArrayType 


ClassOrInterfaceType: 
ClassType 
InterfaceType 


ClassType: 
{Annotation} Typeldentifier [TypeArguments ] 
PackageName . {Annotation} Typeldentifier [TypeArguments] 
ClassOrInterfaceType . {Annotation} Typeldentifier [TypeArguments] 


InterfaceType: 
ClassType 


Type Variable: 
{Annotation} Typeldentifier 


ArrayType: 
PrimitiveType Dims 
ClassOrInterfaceType Dims 
TypeVariable Dims 
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Dims: 
{Annotation} {| | {{Annotation} [ ]} 


The sample code: 


class Point { int[] metrics; } 
interface Move { void move(int deltax, int deltay); } 


declares a class type Point, an interface type Move, and uses an array type int [] (anarray 
of int) to declare the field metrics of the class Point. 


A class or interface type consists of an identifier or a dotted sequence of identifiers, 
where each identifier is optionally followed by type arguments (§4.5.1). If type 
arguments appear anywhere in a class or interface type, it is a parameterized type 


($4.5). 


Each identifier in a class or interface type is classified as a package name or a type 
name (§6.5.1). Identifiers which are classified as type names may be annotated. Ifa 
class or interface type has the form T. id (optionally followed by type arguments), 
then id must be the simple name of an accessible member type of rT (§6.6, $8.5, 
§9.5), or a compile-time error occurs. The class or interface type denotes that 
member type. 


4.3.1 Objects 


An object is a class instance or an array. 


The reference values (often just references) are pointers to these objects, and a 
special null reference, which refers to no object. 


A class instance is explicitly created by a class instance creation expression (§15.9). 
An array is explicitly created by an array creation expression (§15.10.1). 


Other expressions may implicitly create a class instance ($12.5) or an array ($10.6). 


Example 4.3.1-1. Object Creation 


class Point { 
mnt. x= ye 
Point() { System.out.println("default"); } 
Point (int x, int y) { this.x = x; this.y = y; } 


/* A Point instance is explicitly created at 
class initialization time: */ 
static Point origin = new Point (0,0); 
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/* A String can be implicitly created 


by a + operator: */ 
public String toString() 


class Test { 


public static void main(String[] 


{ return "("+x4+4"," 4+ y4+ ")"; } 


args) { 


/* A Point is explicitly created 


using newInstance: */ 


Point p = null; 

try { 
pe 

} catch 


(Point) Class. forName ("Point") .newInstance() ; 
(Exception e) { 


System.out.printin(e); 


/* An array is implicitly created 


by an array initializer: */ 


Point a[] = { new Point(0,0), 


new Point(1,1) }; 


/* Strings are implicitly created 


by + operators: */ 
System.out.printin(" 
System.out.printin(" 


p: "+ pi; 


a: { "+ al0] +", "+ all] +" 3"); 


/* An array is explicitly created 


by an array creation expression: */ 
String sa[] = new String[2]; 


sa[0] = "he"; sa[1] 


System.out.printin(sa[0 


This program produces the output: 


default 

p: (0,0) 

a: { (0,0), 
hello 


(1,1) } 


The operators on references to objects 


= "llo"; 
+ sa[l]); 


are: 


¢ Field access, using either a qualified name (§6.6) or a field access expression 


(§15.11) 
¢ Method invocation (§15.12) 
¢ The cast operator (§5.5, §15.16) 


¢ The string concatenation operator + (§15.18.1), which, when given a string 
operand and a reference, will convert the reference to a String by invoking the 
toString method of the referenced object (using "nu11" if either the reference 
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or the result of toString is a null reference), and then will produce a newly 
created St ring that is the concatenation of the two strings 


¢ The instanceof operator (§15.20.2) 
¢ The reference equality operators == and != (§15.21.3) 
¢ The conditional operator ? : ($15.25). 


There may be many references to the same object. Most objects have state, stored 
in the fields of objects that are instances of classes or in the variables that are the 
components of an array object. If two variables contain references to the same 
object, the state of the object can be modified using one variable's reference to the 
object, and then the altered state can be observed through the reference in the other 
variable. 


Example 4.3.1-2. Primitive and Reference Identity 
class Value { int val; } 


class Test { 

public static void main(String[] args) { 
int il = 3; 
arith, 52: =" aes 
i2 = 4; 
System.out.print ("il=="_+ il); 
System.out.println(" but i2==" + i2); 
Value vl = new Value(); 
vi.val = 5; 
Value v2 = vl; 
v2.val = 6; 
System.out.print ("vl.val=="_ + vl.val); 
System.out.println(" and v2.val==" + v2.val); 


} 
This program produces the output: 


il==3 but i2==4 
vl.val==6 and v2.val==6 


because v1.val and v2.val reference the same instance variable (§4.12.3) in the one 
Value object created by the only new expression, while i1 and i2 are different variables. 


Each object is associated with a monitor ($17.1), which is used by synchronized 
methods (§8.4.3) and the synchronized statement ($14.19) to provide control over 


concurrent access to state by multiple threads (§17 (Threads and Locks)). 
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4.3.2 The Class object 


The class object is a superclass (§8.1.4) of all other classes. 


All class and array types inherit ($8.4.8) the methods of class object, which are 
summarized as follows: 


The method clone is used to make a duplicate of an object. 


The method equals defines a notion of object equality, which is based on value, 
not reference, comparison. 


The method finalize is run just before an object is destroyed (§12.6). 


The method getClass returns the Class object that represents the class of the 
object. 


A Class object exists for each reference type. It can be used, for example, 
to discover the fully qualified name of a class, its members, its immediate 
superclass, and any interfaces that it implements. 


The type of a method invocation expression of getClass is Class<? extends 
|7|>, where Tis the class or interface that was searched for getClass (§15.12.1) 
and |7| denotes the erasure of r (§4.6). 


A class method that is declared synchronized (§8.4.3.6) synchronizes on the 
monitor associated with the class object of the class. 


The method hashCode is very useful, together with the method equals, in 
hashtables such as java.util.HashMap. 


The methods wait, notify, and notifyAll are used in concurrent programming 
using threads (§17.2). 


The method toString returns a String representation of the object. 


4.3.3. The Class string 


Instances of class string represent sequences of Unicode code points. 


A String object has a constant (unchanging) value. 


String literals (§3.10.5) are references to instances of class string. 


The string concatenation operator + (§15.18.1) implicitly creates a new string 
object when the result is not a constant expression (§15.28). 
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4.3.4 When Reference Types Are the Same 


Two reference types are the same compile-time type if they are declared in 
compilation units associated with the same module (§7.3), and they have the same 
binary name ($13.1), and their type arguments, if any, are the same, applying this 
definition recursively. 


When two reference types are the same, they are sometimes said to be the same 
class or the same interface. 


At run time, several reference types with the same binary name may be loaded 
simultaneously by different class loaders. These types may or may not represent 
the same type declaration. Even if two such types do represent the same type 
declaration, they are considered distinct. 


Two reference types are the same run-time type if: 


¢ They are both class or both interface types, are defined by the same class loader, 
and have the same binary name (§13.1), in which case they are sometimes said 
to be the same run-time class or the same run-time interface. 


¢ They are both array types, and their component types are the same run-time type 
($10 (Arrays)). 


4.4 Type Variables 


A type variable is an unqualified identifier used as a type in class, interface, method, 
and constructor bodies. 


A type variable is introduced by the declaration of a type parameter of a generic 
class, interface, method, or constructor (§8.1.2, §9.1.2, §8.4.4, §8.8.4). 


TypeParameter: 
{TypeParameterModifier} Typeldentifier [TypeBound] 


TypeParameterModifier: 
Annotation 


TypeBound: 
extends TypeVariable 
extends ClassOrInterfaceType {AdditionalBound} 
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AdditionalBound: 
& InterfaceType 


The scope of a type variable declared as a type parameter is specified in $6.3. 


Every type variable declared as a type parameter has a bound. If no bound is 
declared for a type variable, object is assumed. If a bound is declared, it consists 
of either: 


* a single type variable r, or 
¢ aclass or interface type T possibly followed by interface types I; & ... & In. 
It is a compile-time error if any of the types I, ... I, is a class type or type variable. 


The erasures (§4.6) of all constituent types of a bound must be pairwise different, 
or a compile-time error occurs. 


A type variable must not at the same time be a subtype of two interface types which 
are different parameterizations of the same generic interface, or a compile-time 
error occurs. 


The order of types in a bound is only significant in that the erasure of a type variable 
is determined by the first type in its bound, and that a class type or type variable 
may only appear in the first position. 


The members of a type variable x with bound 7 « I; & ... & I, are the members of 
the intersection type (§4.9) 7 & I; & ... & In appearing at the point where the type 
variable is declared. 


Example 4.4-1. Members of a Type Variable 
package TypeVarMembers; 


class. C { 
public void mCPublic() {} 
protected void mCProtected() {} 
void mCPackage() {} 
private void mCPrivate() {} 


} 


interface I { 
void mI(); 


} 

class CT extends C implements I { 
public void mI() {} 

} 


class Test { 
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<T extends C & I> void test(T t) { 


t.mI(); // OK 
t.mCPublic(); // OK 
t.mCProtected(); // OK 
t.mCPackage(); // OK 
t.mCPrivate(); // Compile-time error 


} 


The type variable T has the same members as the intersection type C & 1, which in turn 
has the same members as the empty class CT, defined in the same scope with equivalent 
supertypes. The members of an interface are always public, and therefore always inherited 
(unless overridden). Hence mI is a member of cT and of T. Among the members of c, all 
but mcPrivate are inherited by CT, and are therefore members of both cT and T. 


If c had been declared in a different package than T, then the call to mcPackage would 
give rise to a compile-time error, as that member would not be accessible at the point where 
T is declared. 


4.5 Parameterized Types 


A class or interface declaration that is generic (§8.1.2, §9.1.2) defines a set of 
parameterized types. 


A parameterized type is a class or interface type of the form c<Tj,...,T,>, where c 
is the name of a generic type and <T),...,7,> is a list of type arguments that denote 
a particular parameterization of the generic type. 


A generic type has type parameters F),...,.F, with corresponding bounds 8),...,Bp. 
Each type argument rT; of a parameterized type ranges over all types that are 
subtypes of all types listed in the corresponding bound. That is, for each bound 
type sin B;, T; is a subtype of S[F):=T),...,Fn:=Tn] (§4.10). 


A parameterized type C<Tj,...,T,> iS well-formed if all of the following are true: 
¢ cis the name of a generic type. 


¢ The number of type arguments is the same as the number of type parameters in 
the generic declaration of c. 


¢ When subjected to capture conversion (§5.1.10) resulting in the type c<Xj,...,Xn>, 
each type argument x; is a subtype of S[F,:=X1,...,Fn:=Xn] for each bound 
type sin B;. 


It is a compile-time error if a parameterized type is not well-formed. 
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In this specification, whenever we speak of a class or interface type, we include the 
generic version as well, unless explicitly excluded. 


Two parameterized types are provably distinct if either of the following is true: 
¢ They are parameterizations of distinct generic type declarations. 


¢ Any of their type arguments are provably distinct. 


Given the generic types in the examples of §8.1.2, here are some well-formed parameterized 
types: 

* Seq<String> 

* Seq<Seq<String>> 

* Seq<String>.Zipper<Integer> 


° Pair<String, Integer> 
Here are some incorrect parameterizations of those generic types: 


* Seq<int> is illegal, as primitive types cannot be type arguments. 
* Pair<String> is illegal, as there are not enough type arguments. 


* Pair<String, String, String> is illegal, as there are too many type arguments. 


A parameterized type may be an parameterization of a generic class or interface which 
is nested. For example, if a non-generic class c has a generic member class D<T>, then 
C.D<Object> is a parameterized type. And if a generic class c<T> has a non-generic 
member class D, then the member type c<St ring>.D is a parameterized type, even though 
the class D is not generic. 


4.5.1 Type Arguments of Parameterized Types 


Type arguments may be either reference types or wildcards. Wildcards are useful 
in situations where only partial knowledge about the type parameter is required. 


TypeArguments: 
< TypeArgumentList > 


TypeArgumentList: 
TypeArgument {, TypeArgument} 


TypeArgument: 
ReferenceType 
Wildcard 
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Wildcard: 
{Annotation} 2 [WildcardBounds ] 


WildcardBounds: 
extends ReferenceType 
super ReferenceType 


Wildcards may be given explicit bounds, just like regular type variable 
declarations. An upper bound is signified by the following syntax, where B is the 
bound: 


? extends B 


Unlike ordinary type variables declared in a method signature, no type inference 
is required when using a wildcard. Consequently, it is permissible to declare lower 
bounds on a wildcard, using the following syntax, where B is a lower bound: 


2? super B 


The wildcard ? extends Object is equivalent to the unbounded wildcard 2. 
Two type arguments are provably distinct if one of the following is true: 


¢ Neither argument is a type variable or wildcard, and the two arguments are not 
the same type. 


¢ One type argument is a type variable or wildcard, with an upper bound (from 
capture conversion (§5.1.10), if necessary) of s; and the other type argument T 
is not a type variable or wildcard; and neither |s| <: |z] nor |z| <: |s| ($4.8, §4.10). 


¢ Each type argument is a type variable or wildcard, with upper bounds (from 
capture conversion, if necessary) of s and T; and neither |s| <: |z| nor |z| <: |s|. 


A type argument 1; is said to contain another type argument T», written T2 <= T, 
if the set of types denoted by r, is provably a subset of the set of types denoted 
by rT, under the reflexive and transitive closure of the following rules (where <: 
denotes subtyping (§4.10)): 


°¢ ? extends T <=? extends Sif T<: $ 
° ? extends T <=? 

° ? super T<=? super Sif s<:T 

° ? super T <=? 


° ? super T <= ? extends Object 
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° T<=? extends T 


© F<= "2. super T 


The relationship of wildcards to established type theory is an interesting one, which we 
briefly allude to here. Wildcards are a restricted form of existential types. Given a generic 
type declaration G<T extends B>, G<?> is roughly analogous to Some X <: B. G<X>. 


Historically, wildcards are a direct descendant of the work by Atsushi Igarashi and Mirko 
Viroli. Readers interested in a more comprehensive discussion should refer to On Variance- 
Based Subtyping for Parametric Types by Atsushi Igarashi and Mirko Viroli, in the 
Proceedings of the 16th European Conference on Object Oriented Programming (ECOOP 
2002). This work itself builds upon earlier work by Kresten Thorup and Mads Torgersen 
(Unifying Genericity, ECOOP 99), as well as a long tradition of work on declaration based 
variance that goes back to Pierre America's work on POOL (OOPSLA 89). 


Wildcards differ in certain details from the constructs described in the aforementioned 
paper, in particular in the use of capture conversion (§5.1.10) rather than the close 
operation described by Igarashi and Viroli. For a formal account of wildcards, see Wild 
FJ by Mads Torgersen, Erik Ernst and Christian Plesner Hansen, in the 12th workshop on 
Foundations of Object Oriented Programming (FOOL 2005). 


Example 4.5.1-1. Unbounded Wildcards 


import java.util.Collection; 
import java.util.ArrayList; 


class Test { 
static void printCollection(Collection<?> c) { 
// a wildcard collection 
for (Object o : c) { 
System.out.printin(o); 
} 
} 


public static void main(String[] args) { 
Collection<String> cs = new ArrayList<String>(); 
cs.add("hello"); 
cs.add("world"); 
printCollection (cs); 


} 
Note that using Collection<Object> as the type of the incoming parameter, c, would 
not be nearly as useful; the method could only be used with an argument expression that 
had type Collection<Object>, which would be quite rare. In contrast, the use of an 


unbounded wildcard allows any kind of collection to be passed as an argument. 


Here is an example where the element type of an array is parameterized by a wildcard: 
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public Method getMethod(Class<?>[] parameterTypes) { ... } 


Example 4.5.1-2. Bounded Wildcards 


boolean addAll(Collection<? extends E> c) 


Here, the method is declared within the interface Collection<E>, and is designed to add 
all the elements of its incoming argument to the collection upon which it is invoked. A 
natural tendency would be to use Collect ion<E> as the type of c, but this is unnecessarily 
restrictive. An alternative would be to declare the method itself to be generic: 


<T> boolean addAll(Collection<T> c) 


This version is sufficiently flexible, but note that the type parameter is used only once in the 
signature. This reflects the fact that the type parameter is not being used to express any kind 
of interdependency between the type(s) of the argument(s), the return type and/or throws 
type. In the absence of such interdependency, generic methods are considered bad style, 
and wildcards are preferred. 


Reference(T referent, ReferenceQueue<? super T> queue) 


Here, the referent can be inserted into any queue whose element type is a supertype of the 
type T of the referent; T is the lower bound for the wildcard. 


4.5.2 Members and Constructors of Parameterized Types 


Let c be a generic class or interface declaration with type parameters Aj,...,A,, and 
let C<T),...,T,> be a parameterization of c where, for 1 <i <n, T,; is a type (rather 
than a wildcard). Then: 


¢ Let m be a member or constructor declaration in c, whose type as declared is T 
($8.2, §8.8.6). 


The type of min C<T),...,T;> iS T[Al:=T1,.--,An?=Tnl- 


¢ Let mbe a member or constructor declaration in D, where Dis a class extended by c 
or an interface implemented by c. Let D<vj,...,u,> be the supertype of C<Tj,...,Tn> 
that corresponds to b. 


The type of min c<Tj,...,T7,> is the type of min D<Uj,...,Ux>. 
If any of the type arguments in the parameterization of c are wildcards, then: 


¢ The types of the fields, methods, and constructors in C<Tj,...,T,> are the types 
of the fields, methods, and constructors in the capture conversion of C<Tyj,...,Tn> 
(§5.1.10). 
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¢ Let p be a (possibly generic) class or interface declaration in c. Then the type 
of Din C<Ty,...,T,> is D where, if D is generic, all type arguments are unbounded 
wildcards. 


This is of no consequence, as it is impossible to access a member of a parameterized type 
without performing capture conversion, and it is impossible to use a wildcard after the 
keyword new in a class instance creation expression (§15.9). 


The sole exception to the previous paragraph is when a nested parameterized type is used 
as the expression in an instanceof operator (§15.20.2), where capture conversion is not 
applied. 


A static member that is declared in a generic type declaration must be referred 
to using the non-generic type that corresponds to the generic type ($6.1, §6.5.5.2, 
§6.5.6.2), or a compile-time error occurs. 


In other words, it is illegal to refer to a static member declared in a generic type 
declaration by using a parameterized type. 


4.6 Type Erasure 


Type erasure is a mapping from types (possibly including parameterized types and 
type variables) to types (that are never parameterized types or type variables). We 
write |7| for the erasure of type r. The erasure mapping is defined as follows: 


¢ The erasure of a parameterized type (§4.5) G<Tj,...,Tn> is |¢]. 

¢ The erasure of a nested type T.c is |z].c. 

¢ The erasure of an array type T[] is |7z|(1. 

¢ The erasure of a type variable (§4.4) is the erasure of its leftmost bound. 
¢ The erasure of every other type is the type itself. 


Type erasure also maps the signature (§8.4.2) of a constructor or method to a 
signature that has no parameterized types or type variables. The erasure of a 
constructor or method signature s is a signature consisting of the same name as s 
and the erasures of all the formal parameter types given in s. 


The return type of a method (§8.4.5) and the type parameters of a generic method 
or constructor (§8.4.4, §8.8.4) also undergo erasure if the method or constructor's 
signature is erased. 


The erasure of the signature of a generic method has no type parameters. 
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4.7 Reifiable Types 


Because some type information is erased during compilation, not all types are 
available at run time. Types that are completely available at run time are known 


as reifiable types. 


A type is reifiable if and only if one of the following holds: 


¢ It refers to a non-generic class or interface type declaration. 


It is a parameterized type in which all type arguments are unbounded wildcards 
($4.5.1). 


It is araw type (§4.8). 
It is a primitive type (§4.2). 


It is an array type ($10.1) whose element type is reifiable. 


wom 


It is a nested type where, for each type r separated by a".", r itself is reifiable. 


For example, if a generic class x<T> has a generic member class y<u>, then the 
type X<?>. Y<?> is reifiable because x<?> is reifiable and y<?> is reifiable. The type 
X<?>.Y¥<Object> is not reifiable because y<Object> is not reifiable. 


An intersection type is not reifiable. 


The decision not to make all generic types reifiable is one of the most crucial, and 
controversial design decisions involving the type system of the Java programming 
language. 


Ultimately, the most important motivation for this decision is compatibility with existing 
code. In a naive sense, the addition of new constructs such as generics has no implications 
for pre-existing code. The Java programming language, per se, is compatible with earlier 
versions as long as every program written in the previous versions retains its meaning in 
the new version. However, this notion, which may be termed language compatibility, is 
of purely theoretical interest. Real programs (even trivial ones, such as "Hello World") 
are composed of several compilation units, some of which are provided by the Java SE 
Platform (such as elements of java.lang or java.util). In practice, then, the minimum 
requirement is platform compatibility - that any program written for the prior version of the 
Java SE Platform continues to function unchanged in the new version. 


One way to provide platform compatibility is to leave existing platform functionality 
unchanged, only adding new functionality. For example, rather than modify the existing 
Collections hierarchy in java.util, one might introduce a new library utilizing generics. 


The disadvantages of such a scheme is that it is extremely difficult for pre-existing clients 
of the Collection library to migrate to the new library. Collections are used to exchange 
data between independently developed modules; if a vendor decides to switch to the new, 
generic, library, that vendor must also distribute two versions of their code, to be compatible 
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with their clients. Libraries that are dependent on other vendors code cannot be modified to 
use generics until the supplier's library is updated. If two modules are mutually dependent, 
the changes must be made simultaneously. 


Clearly, platform compatibility, as outlined above, does not provide a realistic path for 
adoption of a pervasive new feature such as generics. Therefore, the design of the generic 
type system seeks to support migration compatibility. Migration compatibility allows the 
evolution of existing code to take advantage of generics without imposing dependencies 
between independently developed software modules. 


The price of migration compatibility is that a full and sound reification of the generic type 
system is not possible, at least while the migration is taking place. 


4.8 Raw Types 


To facilitate interfacing with non-generic legacy code, it is possible to use as a type 
the erasure (§4.6) of a parameterized type ($4.5) or the erasure of an array type 
($10.1) whose element type is a parameterized type. Such a type is called a raw 


type. 


More precisely, a raw type is defined to be one of: 


¢ The reference type that is formed by taking the name of a generic type declaration 
without an accompanying type argument list. 


¢ An array type whose element type is a raw type. 


¢ Anon-static member type of a raw type R that is not inherited from a superclass 
or superinterface of R. 


A non-generic class or interface type is not a raw type. 


To see why a non-static type member of a raw type is considered raw, consider the 
following example: 


class Outer<T>{ 
HN Br 
class Inner { 
T setOuterT(T t1) { t = tl; return t; } 
} 
} 


The type of the member(s) of Inner depends on the type parameter of Outer. If Outer is 
raw, Inner must be treated as raw as well, as there is no valid binding for T. 
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This rule applies only to type members that are not inherited. Inherited type members that 
depend on type variables will be inherited as raw types as a consequence of the rule that 
the supertypes of a raw type are erased, described later in this section. 


Another implication of the rules above is that a generic inner class of a raw type can itself 
only be used as a raw type: 


class Outer<T>{ 
class Inner<S> { 
S s; 


} 


It is not possible to access Inner as a partially raw type (a "rare" type): 


Outer.Inner<Double> x = null; // illegal 
Double d = x.s; 


because Outer itself is raw, hence so are all its inner classes including Inner, and so it is 
not possible to pass any type arguments to Inner. 


The superclasses (respectively, superinterfaces) of a raw type are the erasures of the 
superclasses (superinterfaces) of any of the parameterizations of the generic type. 


The type of a constructor (§8.8), instance method (§8.4, §9.4), or non-static field 
($8.3) of a raw type c that is not inherited from its superclasses or superinterfaces 
is the raw type that corresponds to the erasure of its type in the generic declaration 
corresponding to c. 


The type of a static method or static field of a raw type cis the same as its type 
in the generic declaration corresponding to c. 


It is a compile-time error to pass type arguments to a non-static type member of 
a raw type that is not inherited from its superclasses or superinterfaces. 


It is a compile-time error to attempt to use a type member of a parameterized type 
as a raw type. 


This means that the ban on "rare" types extends to the case where the qualifying type is 
parameterized, but we attempt to use the inner class as a raw type: 


Outer<Integer>.Inner x = null; // illegal 


This is the opposite of the case discussed above. There is no practical justification for this 
half-baked type. In legacy code, no type arguments are used. In non-legacy code, we should 
use the generic types correctly and pass all the required type arguments. 
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The supertype of a class may be a raw type. Member accesses for the class are 
treated as normal, and member accesses for the supertype are treated as for raw 
types. In the constructor of the class, calls to super are treated as method calls on 
a raw type. 


The use of raw types is allowed only as a concession to compatibility of legacy 
code. The use of raw types in code written after the introduction of generics into 
the Java programming language is strongly discouraged. It is possible that future 
versions of the Java programming language will disallow the use of raw types. 


To make sure that potential violations of the typing rules are always flagged, some 
accesses to members of a raw type will result in compile-time unchecked warnings. 
The rules for compile-time unchecked warnings when accessing members or 
constructors of raw types are as follows: 


e At an assignment to a field: if the type of the Primary in the field access 
expression (§15.11) is araw type, then a compile-time unchecked warning occurs 
if erasure changes the field's type. 


¢ Atan invocation of a method or constructor: if the type of the class or interface to 
search (§15.12.1) is a raw type, then a compile-time unchecked warning occurs if 
erasure changes any of the formal parameter types of the method or constructor. 


¢ No compile-time unchecked warning occurs for a method call when the formal 
parameter types do not change under erasure (even if the return type and/or 
throws Clause changes), for reading from a field, or for a class instance creation 
of a raw type. 


Note that the unchecked warnings above are distinct from the unchecked warnings possible 
from narrowing reference conversion (§5.1.6), unchecked conversion (§5.1.9), method 
declarations (§8.4.1, §8.4.8.3), and certain expressions (§15.12.4.2, §15.13.2, §15.27.3). 


The warnings here cover the case where a legacy consumer uses a generified library. For 
example, the library declares a generic class Foo<T extends String> that has a field £ 
of type Vector<T>, but the consumer assigns a vector of integers to e. £ where e has the 
raw type Foo. The legacy consumer receives a warning because it may have caused heap 
pollution (§4.12.2) for generified consumers of the generified library. 


(Note that the legacy consumer can assign a Vector<String> from the library to its own 
Vector variable without receiving a warning. That is, the subtyping rules (§4.10.2) of the 
Java programming language make it possible for a variable of a raw type to be assigned a 
value of any of the type's parameterized instances.) 


The warnings from unchecked conversion cover the dual case, where a generified consumer 
uses a legacy library. For example, a method of the library has the raw return type 
Vector, but the consumer assigns the result of the method invocation to a variable of type 
Vector<String>. This is unsafe, since the raw vector might have had a different element 
type than String, but is still permitted using unchecked conversion in order to enable 
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interfacing with legacy code. The warning from unchecked conversion indicates that the 
generified consumer may experience problems from heap pollution at other points in the 
program. 


Example 4.8-1. Raw Types 


class Cell<E> { 


E value; 
Cell (E v) { value = v; } 
E get () { return value; } 


void set(E v) { value = v; } 


public static void main(String[] args) { 
Cell x = new Cell<String>("abc") ; 
System.out.println(x.value); // OK, has type Object 
System.out.println(x.get()); // OK, has type Object 
x.set ("def"); // unchecked warning 


Example 4.8-2. Raw Types and Inheritance 


import java.util.*; 
class NonGeneric { 
Collection<Number> myNumbers() { return null; } 


abstract class RawMembers<T> extends NonGeneric 
implements Collection<String> { 
static Collection<NonGeneric> cng = 
new ArrayList<NonGeneric>(); 


public static void main(String[] args) { 
RawMembers rw = null; 


Collection<Number> cn = rw.myNumbers() ; 
// OK 
Iterator<String> is = rw.iterator(); 
// Unchecked warning 
Collection<NonGeneric> cnn = rw.cng; 


// OK, static member 


In this program (which is not meant to be run), RawMembers<T> inherits the method: 


Iterator<String> iterator () 


from the Collection<String> superinterface. The raw type RawMembers inherits 
iterator () from Collection, the erasure of Collect ion<String>, which means that 
the return type of iterator() in RawMembers is Iterator. As a result, the attempt to 
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assign rw.iterator() to Iterator<String> requires an unchecked conversion, so a 
compile-time unchecked warning is issued. 


In contrast, RawMembers inherits myNumbers() from the NonGeneric class whose 
erasure is also NonGeneric. Thus, the return type of myNumbers () in RawMembers is not 
erased, and the attempt to assign rw.myNumbers () to Collect ion<Number> requires no 
unchecked conversion, so no compile-time unchecked warning is issued. 


Similarly, the static member cng retains its parameterized type even when accessed 
through a object of raw type. Note that access to a static member through an instance is 
considered bad style and is discouraged. 


This example reveals that certain members of a raw type are not erased, namely static 
members whose types are parameterized, and members inherited from a non-generic 
supertype. 


Raw types are closely related to wildcards. Both are based on existential types. Raw types 
can be thought of as wildcards whose type rules are deliberately unsound, to accommodate 
interaction with legacy code. Historically, raw types preceded wildcards; they were first 
introduced in GJ, and described in the paper Making the future safe for the past: Adding 
Genericity to the Java Programming Language by Gilad Bracha, Martin Odersky, David 
Stoutamire, and Philip Wadler, in Proceedings of the ACM Conference on Object-Oriented 
Programming, Systems, Languages and Applications (OOPSLA 98), October 1998. 


4.9 Intersection Types 


An intersection type takes the form T, « ... & T,(m > 0), where rT; (1 Si <n) are types. 


Intersection types can be derived from type parameter bounds (§4.4) and cast 
expressions (§15.16); they also arise in the processes of capture conversion 
(§5.1.10) and least upper bound computation (§4.10.4). 


The values of an intersection type are those objects that are values of all of the 
types T; for] Si<n. 


Every intersection type 1; & ... & T, induces a notional class or interface for the 
purpose of identifying the members of the intersection type, as follows: 


¢ For each r; (1 <i <n), let c; be the most specific class or array type such that 
T; <: C;. Then there must be some c, such that c, <: c; for any i (1 <i<n), or 
a compile-time error occurs. 


¢ For 1 <j <n, if 7; is a type variable, then let 7;' be an interface whose members 
are the same as the public members of 1,; otherwise, if 7; is an interface, then 
let r,' be r. 
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e If c, iS Object, a notional interface is induced; otherwise, a notional class 
is induced with direct superclass c,. This class or interface has direct 
superinterfaces T,’, ..., T,' and is declared in the package in which the intersection 


type appears. 


The members of an intersection type are the members of the class or interface it 
induces. 


It is worth dwelling upon the distinction between intersection types and the bounds of type 
variables. Every type variable bound induces an intersection type. This intersection type is 
often trivial, consisting of a single type. The form of a bound is restricted (only the first 
element may be a class or type variable, and only one type variable may appear in the 
bound) to preclude certain awkward situations coming into existence. However, capture 
conversion can lead to the creation of type variables whose bounds are more general, such 
as array types). 


4.10 Subtyping 


The subtype and supertype relations are binary relations on types. 


The supertypes of a type are obtained by reflexive and transitive closure over the 
direct supertype relation, written s >, 7, which is defined by rules given later in 
this section. We write s :> Tr to indicate that the supertype relation holds between 
sand T. 


Sis a proper supertype of T, written s > T, if s :> Tand s#T. 


The subtypes of a type rT are all types u such that rT is a supertype of vu, and the 
null type. We write rT <: sto indicate that that the subtype relation holds between 
types T and s. 


Tis a proper subtype of s, written T< s,if T<: sand s¥#T. 
Tis a direct subtype of s, written T <, s, if s >, T. 


Subtyping does not extend through parameterized types: T <: s does not imply that 
C<T> <: C<S>. 


4.10.1 Subtyping among Primitive Types 
The following rules define the direct supertype relation among the primitive types: 
® double >, float 


° float >; long 
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° long >; int 
® int >, char 
* int >, short 


® short >; byte 


4.10.2 Subtyping among Class and Interface Types 


Given a non-generic type declaration c, the direct supertypes of the type c are all 
of the following: 


e The direct superclass of c (§8.1.4). 
¢ The direct superinterfaces of c (§8.1.5). 
¢ The type object, if cis an interface type with no direct superinterfaces (§9.1.3). 


Given a generic type declaration c<F),...,F,> (n > 0), the direct supertypes of the 
raw type c (§4.8) are all of the following: 


¢ The direct superclass of the raw type c. 
¢ The direct superinterfaces of the raw type c. 


e The type object, if C<Fj,...,.F,> iS a generic interface type with no direct 
superinterfaces (§9.1.2). 


Given a generic type declaration c<F),...,F,> (n > 0), the direct supertypes of the 
generic type C<Fy,...,F,> are all of the following: 


¢ The direct superclass of c<F),...,Fn>- 
¢ The direct superinterfaces of c<F),...,Fn>. 


e The type object, if C<Fj,...,.F,> iS a generic interface type with no direct 
superinterfaces. 


¢ The raw type c. 


Given a generic type declaration cC<F),...,F,> (n > 0), the direct supertypes of 
the parameterized type C<Tj,...,T,>, where T; (1 <i <n) is a type, are all of the 
following: 


© D<U; 9,...,U, 8>, where D<U;,...,U,> 18 a generic type which is a direct supertype 
of the generic type C<F),...,F,> and 9 is the substitution [F):=T),...,Fn:=Tnl- 


* C<S1,...,S,>, Where s; contains T; (1 <i<n) (§4.5.1). 
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e The type object, if C<F,...,.F,> iS a generic interface type with no direct 
superinterfaces. 


¢ The raw type c. 


Given a generic type declaration c<F),...,F,> (n > 0), the direct supertypes of the 
parameterized type c<R,...,R,> where at least one of the r; (1 <i <n) is a wildcard 
type argument, are the direct supertypes of the parameterized type c<xj,...,Xn> 
which is the result of applying capture conversion to C<Rj,...,Rn> (§$5.1.10). 


The direct supertypes of an intersection type T, & ... & T, are T; (1 Sin). 
The direct supertypes of a type variable are the types listed in its bound. 
A type variable is a direct supertype of its lower bound. 


The direct supertypes of the null type are all reference types other than the null 
type itself. 


4.10.3 Subtyping among Array Types 
The following rules define the direct supertype relation among array types: 
¢ If sand rare both reference types, then s[] >, T[] iff s>, Tf. 
* Object >; Object [] 
* Cloneable >; Object [] 
® java.io.Serializable >; Object [] 
¢ If pis a primitive type, then: 
— Object >; P[] 
— Cloneable >, P[] 


— java.io.Serializable >, P[] 


4.10.4 Least Upper Bound 


The least upper bound, or "lub", of a set of reference types is a shared supertype that 
is more specific than any other shared supertype (that is, no other shared supertype 
is a subtype of the least upper bound). This type, lub(v;, ..., u;,), is determined as 
follows. 


If k = 1, then the lub is the type itself: lub(v) = v. 


Otherwise: 
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¢ For each uv; (1 Si<k): 
Let ST(u:) be the set of supertypes of u;. 
Let EST(u;), the set of erased supertypes of v;, be: 
EST(u,) = { |w | win ST(u;) } where |n is the erasure of w. 


The reason for computing the set of erased supertypes is to deal with situations where 
the set of types includes several distinct parameterizations of a generic type. 


For example, given List<String> and List<Object>, simply intersecting the 
sets ST(List<String>) = { List<String>, Collection<String>, Object } and 
ST(List<Object>) = { List<Object>, Collection<Object>, Object } would 
yield a set { Object }, and we would have lost track of the fact that the upper bound 
can safely be assumed to be a List. 


In contrast, intersecting EST(List<String>) = { List, Collection, Object } and 
EST(List<Object>) = { List, Collection, Object } yields { List, Collection, 
Object }, which will eventually enable us to produce List<?>. 


¢ Let EC, the erased candidate set for uv, ... U;,, be the intersection of all the sets 
EST(u,) 1 Sisk). 


¢ Let MEC, the minimal erased candidate set for U, ... U,, be: 


MEC = { v| vin EC, and for all w# vin EC, it is not the case that w<: v} 


Because we are seeking to infer more precise types, we wish to filter out any candidates 
that are supertypes of other candidates. This is what computing MEC accomplishes. In 
our running example, we had EC = { List, Collection, Object }, so MEC = { List 
}. The next step is to recover type arguments for the erased types in MEC. 


¢ For any element cof MEC that is a generic type: 
Let the "relevant" parameterizations of c, Relevant(c), be: 


Relevant(c) = { v| 1 <i<k: vin ST(u,) and v= «x...> } 


In our running example, the only generic element of MEC is List, and Relevant(List) 
= { List<String>, List<Object> }. We will now seek to find a type argument for 
List that contains (§4.5.1) both String and Object. 


This is done by means of the least containing parameterization (Icp) operation defined 
below. The first line defines Icp() on a set, such as Relevant(List), as an operation on a 
list consisting of the elements of the set. The next line defines the operation on such a list 
as a pairwise reduction on the elements of the list. The third line is the definition of IcpQ 
on pairs of parameterized types, which in turn relies on the notion of least containing 
type argument (Icta). Icta() is defined for all possible cases. 
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Let the "candidate" parameterization of c, Candidate(c), be the most 
specific parameterization of the generic type c that contains all the relevant 
parameterizations of c: 


Candidate(c) = lcp(Relevant(c)) 
where Icp(), the least containing parameterization, is: 
— Icp(s) = Iep(ei, ..., en) where e; (1 <i<n)ins 
— Icp(e, ..., en) = lep(cp(e:, e2), 3, «+5 En) 
— lep(G<x1, ..., Xn>, G<Y1, «5 Yn>) = G<Icta(x;, Y;), ..., lota(x,, Yn)> 
— lep(G<Xj, ..., Xn>) = G<Icta(x;), ..., leta(x,)> 
and where Icta(), the least containing type argument, is: (assuming u and v are 
types) 
— Icta(u, v) = vif v= v, otherwise ? extends lub(y, v) 
— Icta(u, ? extends V) = ? extends lub(y, v) 
— Icta(u, ? super V) =? super glb(y, v) 
— Icta(? extends U, ? extends V) = ? extends lub(y, v) 
— Icta(? extends U, ? super V) =? 
— Icta(? super U, ? super V) = ? super glb(u, v) 
— |cta(v) = ? if v's upper bound is object, otherwise ? extends lub(u,object) 
and where glb() is as defined in §5.1.10. 
¢ Let lub(v; ... U;) be: 
Best(w,) & ... & Best(w,) 


where w; (1 <i <,7r) are the elements of MEC, the minimal erased candidate set 
of Op ven igs 


and where, if any of these elements are generic, we use the candidate 
parameterization (so as to recover type arguments): 


Best(x) = Candidate(x) if x is generic; x otherwise. 


Strictly speaking, this lub(Q) function only approximates a least upper bound. 
Formally, there may exist some other type Tsuch that all of uv; ... u, are subtypes of T 
and Tis a subtype of lub(v, ..., u,). However, a compiler for the Java programming 
language must implement lub() as specified above. 
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It is possible that the lub() function yields an infinite type. This is permissible, and 
a compiler for the Java programming language must recognize such situations and 
represent them appropriately using cyclic data structures. 


The possibility of an infinite type stems from the recursive calls to lub(). Readers familiar 
with recursive types should note that an infinite type is not the same as a recursive type. 


4.10.5 Type Projections 


A synthetic type variable is a type variable introduced by the compiler during 
capture conversion (§5.1.10) or inference variable resolution (§18.4). 


It is sometimes necessary to find a close supertype of a type, where that supertype 
does not mention certain synthetic type variables. This is achieved with an upward 
projection applied to the type. 


Similarly, a downward projection may be applied to find a close subtype of a type, 
where that subtype does not mention certain synthetic type variables. Because such 
a type does not always exist, downward projection is a partial function. 


These operations take as input a set of type variables that should no longer 
be referenced, referred to as the restricted type variables. When the operations 
recur, the set of restricted type variables is implicitly passed on to the recursive 
application. 


The upward projection of a type rT with respect to a set of restricted type variables 
is defined as follows: 


¢ If rdoes not mention any restricted type variable, then the result is rT. 


¢ If ris a restricted type variable, then the result is the upward projection of the 
upper bound of r. 


¢ If ris a parameterized class type or a parameterized interface type, G<A,...,An>, 
then the result is G<A,',...,4,'>, where, for 1 < i <n, a;' is derived from A; as 
follows: 


— If a; does not mention any restricted type variable, then a,' = a;. 


— If a; is a type that mentions a restricted type variable, then let vu be the upward 
projection of a;. A,’ is a wildcard, defined by three cases: 


>» If vis not object, and if either the declared bound of the ith parameter of 
G, B;, Mentions a type parameter of G, or B; is not a subtype of u, then a,’ is 
an upper-bounded wildcard, ? extends U. 
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>» Otherwise, if the downward projection of A; is L, then a,’ is a lower-bounded 
wildcard, ? super L. 


>» Otherwise, the downward projection of a; is undefined and a,' is an 
unbounded wildcard, ?. 


— If a; is an upper-bounded wildcard that mentions a restricted type variable, 
then let vu be the upward projection of the wildcard bound. a;' is an upper- 
bounded wildcard, ? extends U. 


— If a; is alower-bounded wildcard that mentions a restricted type variable, then 
if the downward projection of the wildcard bound is 1, then a,’ is a lower- 
bounded wildcard, ? super 1; if the downward projection of the wildcard 
bound is undefined, then a;' is an unbounded wildcard, ?. 


¢ If ris an array type, s[], then the result is an array type whose component type 
is the upward projection of s. 


¢ If ris an intersection type, then the result is an intersection type. For each 
element, s, of 7, the result has as an element the upward projection of s. 


The downward projection of a type r with respect to a set of restricted type variables 
is a partial function, defined as follows: 


¢ If rdoes not mention any restricted type variable, then the result is rT. 


¢ If ris arestricted type variable, then if r has a lower bound, and if the downward 
projection of that bound is 1, the result is 2; if r has no lower bound, or if the 
downward projection of that bound is undefined, then the result is undefined. 


¢ If ris a parameterized class type or a parameterized interface type, G<Aj,...,An>, 
then the result is c<ay',...,4,'>, if, for 1 <i <n, a type argument a,' can be derived 
from a; as follows; if not, the result is undefined: 


— If a; is does not mention a restricted type variable, then a,' = a;. 
— If a; is a type that mentions a restricted type variable, then a,' is undefined. 


— If a; is an upper-bounded wildcard that mentions a restricted type variable, 
then if the downward projection of the wildcard bound is u, then a,’ is an upper- 
bounded wildcard, ? extends u; if the downward projection of the wildcard 
bound is undefined, then a;' is undefined. 


— If a; is alower-bounded wildcard that mentions a restricted type variable, then 
let z be the upward projection of the wildcard bound. a,;' is a lower-bounded 
wildcard, ? super L. 
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¢ If ris an array type, s[], then if the downward projection of s is s’, the result is 
S'(]; if the downward projection of s is undefined, then the result is undefined. 


¢ If ris an intersection type, then if the downward projection is defined for each 
element of 1, the result is an intersection type whose elements are the downward 
projections of the elements of 1; if the downward projection is undefined for any 
element of 1, then the result is undefined. 


Like lub (§4.10.4), upward projection and downward projection may produce 
infinite types, due to the recursion on type variable bounds. 


4.11 Where Types Are Used 


Types are used in most kinds of declaration and in certain kinds of expression. 
Specifically, there are 16 type contexts where types are used: 


¢ In declarations: 


1. A type in the extends or implements clause of a class declaration (§8.1.4, 
§8.1.5, $8.5, 89.5) 


2. A type in the extends clause of an interface declaration (§9.1.3, §8.5, §9.5) 


3. The return type of a method (including the type of an element of an 
annotation type) (§8.4.5, §9.4, §9.6.1) 


4. A type in the throws clause of a method or constructor (§8.4.6, §8.8.5, $9.4) 


A type in the extends clause of a type parameter declaration of a generic 
class, interface, method, or constructor (§8.1.2, §9.1.2, §8.4.4, §8.8.4) 


6. The type in a field declaration of a class or interface (including an enum 
constant) (§8.3, §9.3, §8.9.1) 


7. The type in a formal parameter declaration of a method, constructor, or 
lambda expression (§8.4.1, §8.8.1, §9.4, §15.27.1) 


8. The type of the receiver parameter of a method (88.4) 
9. The type ina local variable declaration ($14.4, §14.14.1, §14.14.2, $14.20.3) 
10. The type in an exception parameter declaration (§ 14.20) 


¢ In expressions: 
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11. A type in the explicit type argument list to an explicit constructor invocation 
statement or class instance creation expression or method invocation 
expression (§8.8.7.1, §15.9, §15.12) 


12. In an unqualified class instance creation expression, as the class type to be 
instantiated ($15.9) or as the direct superclass or direct superinterface of an 
anonymous class to be instantiated (§ 15.9.5) 


13. The element type in an array creation expression (§15.10.1) 
14. The type in the cast operator of a cast expression ($15.16) 
15. The type that follows the instanceof relational operator (§15.20.2) 


16. In a method reference expression (§15.13), as the reference type to search 
for a member method or as the class type or array type to construct. 


Also, types are used as: 
¢ The element type of an array type in any of the above contexts; and 


¢ A non-wildcard type argument, or a bound of a wildcard type argument, of a 
parameterized type in any of the above contexts. 


Finally, there are three special terms in the Java programming language which 
denote the use of a type: 


¢ An unbounded wildcard (§4.5.1) 
¢ The ... inthe type of a variable arity parameter (§8.4.1), to indicate an array type 


¢ The simple name of a type in a constructor declaration ($8.8), to indicate the 
class of the constructed object 


The meaning of types in type contexts is given by: 
¢ §4.2, for primitive types 
¢ §4.4, for type parameters 


¢ §4.5, for class and interface types that are parameterized, or appear either as type 
arguments in a parameterized type or as bounds of wildcard type arguments in 
a parameterized type 


¢ §4.8, for class and interface types that are raw 
¢ §4.9, for intersection types in the bounds of type parameters 


¢ §6.5, for class and interface types in contexts where genericity is unimportant 


($6.1) 
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¢ §10.1, for array types 
Some type contexts restrict how a reference type may be parameterized: 


¢ The following type contexts require that if a type is a parameterized reference 
type, it has no wildcard type arguments: 


— In an extends or implements Clause of a class declaration (§8.1.4, §8.1.5) 
— In an extends clause of an interface declaration (§9.1.3) 


— In an unqualified class instance creation expression, as the class type to be 
instantiated ($15.9) or as the direct superclass or direct superinterface of an 
anonymous class to be instantiated (§ 15.9.5) 


— Ina method reference expression ($15.13), as the reference type to search for 
a member method or as the class type or array type to construct. 


In addition, no wildcard type arguments are permitted in the explicit type 
argument list to an explicit constructor invocation statement or class instance 
creation expression or method invocation expression or method reference 
expression (§8.8.7.1, §15.9, §15.12, §15.13). 


¢ The following type contexts require that if a type is a parameterized reference 
type, it has only unbounded wildcard type arguments (i.e. it is a reifiable type) : 


— As the element type in an array creation expression (§15.10.1) 
— As the type that follows the instanceof relational operator (§15.20.2) 


¢ The following type contexts disallow a parameterized reference type altogether, 
because they involve exceptions and the type of an exception is non-generic 
($6.1): 
— As the type of an exception that can be thrown by a method or constructor 


(§8.4.6, §8.8.5, 89.4) 


— In an exception parameter declaration ($14.20) 


In any type context where a type is used, it is possible to annotate the keyword denoting 
a primitive type or the /dentifier denoting the simple name of a reference type. It is also 
possible to annotate an array type by writing an annotation to the left of the [ at the desired 
level of nesting in the array type. Annotations in these locations are called type annotations, 
and are specified in §9.7.4. Here are some examples: 


* @Foo int[] f; annotates the primitive type int 
* int @Foo [] f; annotates the array type int [] 


* int @Foo [][] f; annotates the array type int [] [] 
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* int[] @Foo [] £; annotates the array type int [] which is the component type of 
the array type int [] [] 


Five of the type contexts which appear in declarations occupy the same syntactic real estate 
as a number of declaration contexts (§9.6.4.1): 


¢ The return type of a method (including the type of an element of an annotation type) 
¢ The type in a field declaration of a class or interface (including an enum constant) 


¢ The type in a formal parameter declaration of a method, constructor, or lambda 
expression 


¢ The type in a local variable declaration 


¢ The type in an exception parameter declaration 


The fact that the same syntactic location in a program can be both a type context and a 
declaration context arises because the modifiers for a declaration immediately precede the 
type of the declared entity. §9.7.4 explains how an annotation in such a location is deemed 
to appear in a type context or a declaration context or both. 


Example 4.11-1. Usage of a Type 


import java.util.Random; 
import java.util.Collection; 
import java.util.ArrayList; 


class MiscMath<T extends Number> { 
int divisor; 
MiscMath(int divisor) { this.divisor = divisor; } 
float ratio(long 1) { 
try { 
1 /= divisor; 
} catch (Exception e) { 
if (e instanceof ArithmeticException) 
1 = Long.MAX_VALUE; 
else 
1 = 0; 
} 
return (float)1; 
} 


double gausser() { 
Random r = new Random() ; 
double[] val = new double[2]; 
val[0] = r.nextGaussian(); 
val[1] = r.nextGaussian(); 
return (val[0] + val[1]) / 2; 


} 

Collection<Number> fromArray(Number[] na) { 
Collection<Number> cn = new ArrayList<Number>(); 
for (Number n : na) cn.add(n); 
return cn; 
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<S> void loop(S s) { this.<S>loop(s); } 


In this example, types are used in declarations of the following: 
¢ Imported types (§7.5); here the type Random, imported from the type 
java.util.Random of the package java.util, is declared 


¢ Fields, which are the class variables and instance variables of classes (§8.3), and 
constants of interfaces (§9.3); here the field divisor in the class MiscMath is declared 
to be of type int 


¢ Method parameters (§8.4.1); here the parameter 1 of the method ratio is declared to 
be of type long 


¢ Method results (§8.4); here the result of the method ratio is declared to be of type 
float, and the result of the method gausser is declared to be of type double 


¢ Constructor parameters (§8.8.1); here the parameter of the constructor for MiscMath is 
declared to be of type int 


¢ Local variables (§14.4, §14.14); the local variables r and val of the method gausser 
are declared to be of types Random and double [] (array of double) 


¢ Exception parameters ($14.20); here the exception parameter e of the catch clause is 
declared to be of type Exception 


¢ Type parameters (§4.4); here the type parameter of MiscMath is a type variable T with 
the type Number as its declared bound 


¢ In any declaration that uses a parameterized type; here the type Number is used as a type 
argument (§4.5.1) in the parameterized type Collect ion<Number>. 

and in expressions of the following kinds: 

¢ Class instance creations (§15.9); here a local variable r of method gausser is initialized 
by aclass instance creation expression that uses the type Random 


¢ Generic class (§8.1.2) instance creations (§15.9); here Number is used as a type argument 
in the expression new ArrayList<Number> () 


e Array creations (§15.10.1); here the local variable val of method gausser is initialized 
by an array creation expression that creates an array of double with size 2 


¢ Generic method (§8.4.4) or constructor (§8.8.4) invocations (§15.12); here the method 
loop calls itself with an explicit type argument s 


¢ Casts (§15.16); here the return statement of the method ratio uses the float type 
in a cast 


¢ The instanceof operator (§15.20.2); here the instanceof operator tests whether e is 
assignment-compatible with the type Arithmet icException 
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4.12 Variables 


A variable is a storage location and has an associated type, sometimes called its 
compile-time type, that is either a primitive type ($4.2) or a reference type (§4.3). 


A variable's value is changed by an assignment ($15.26) or by a prefix or postfix + 
+ (increment) or -- (decrement) operator (§15.14.2, §15.14.3, §15.15.1, §15.15.2). 


Compatibility of the value of a variable with its type is guaranteed by the design of 
the Java programming language, as long as a program does not give rise to compile- 
time unchecked warnings (§4.12.2). Default values (§4.12.5) are compatible and all 
assignments to a variable are checked for assignment compatibility ($5.2), usually 
at compile time, but, in a single case involving arrays, a run-time check is made 
($10.5). 


4.12.1 Variables of Primitive Type 


A variable of a primitive type always holds a primitive value of that exact primitive 
type. 


4.12.2 Variables of Reference Type 


A variable of a class type r can hold a null reference or a reference to an instance 
of class r or of any class that is a subclass of rT. 


A variable of an interface type can hold a null reference or a reference to any 
instance of any class that implements the interface. 


Note that a variable is not guaranteed to always refer to a subtype of its declared type, but 
only to subclasses or subinterfaces of the declared type. This is due to the possibility of 
heap pollution discussed below. 


If ris a primitive type, then a variable of type "array of r" can hold a null reference 
or a reference to any array of type "array of rT". 


If ris a reference type, then a variable of type "array of 7" can hold a null reference 
or a reference to any array of type "array of s" such that type s is a subclass or 
subinterface of type T. 


A variable of type object [] can hold a reference to an array of any reference type. 


A variable of type object can hold a null reference or a reference to any object, 
whether it is an instance of a class or an array. 
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It is possible that a variable of a parameterized type will refer to an object that is 
not of that parameterized type. This situation is known as heap pollution. 


Heap pollution can only occur if the program performed some operation involving 
araw type that would give rise to a compile-time unchecked warning (84.8, §5.1.6, 
§5.1.9, §8.4.1, §8.4.8.3, §8.4.8.4, §9.4.1.2, §15.12.4.2), or if the program aliases an 
array variable of non-reifiable element type through an array variable of a supertype 
which is either raw or non-generic. 


For example, the code: 


List 1 = new ArrayList<Number>(); 
List<String> ls = 1; // Unchecked warning 


gives rise to a compile-time unchecked warning, because it is not possible to ascertain, 
either at compile time (within the limits of the compile-time type checking rules) or at run 
time, whether the variable 1 does indeed refer to a List<String>. 


If the code above is executed, heap pollution arises, as the variable 1s, declared to be a 
List<String>, refers to a value that is not in fact a List<String>. 


The problem cannot be identified at run time because type variables are not reified, and 
thus instances do not carry any information at run time regarding the type arguments used 
to create them. 


In a simple example as given above, it may appear that it should be straightforward to 
identify the situation at compile time and give an error. However, in the general (and typical) 
case, the value of the variable 1 may be the result of an invocation of a separately compiled 
method, or its value may depend upon arbitrary control flow. The code above is therefore 
very atypical, and indeed very bad style. 


Furthermore, the fact that Object [] is a supertype of all array types means that unsafe 
aliasing can occur which leads to heap pollution. For example, the following code compiles 
because it is statically type-correct: 


static void m(List<String>... stringLists) { 
Object [] array = stringLists; 
List<Integer> tmpList = Arrays.asList (42); 
array[0] = tmpList; // (1) 


String s = stringLists[0].get(0); // (2) 


Heap pollution occurs at (1) because a component in the stringLists array that should 
refer to a List <String> now refers to a List<Integer>. There is no way to detect this 
pollution in the presence of both a universal supertype (Object []) and anon-reifiable type 
(the declared type of the formal parameter, List<String>[]). No unchecked warning is 
justified at (1); nevertheless, at run time, a ClassCastException will occur at (2). 
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The variable will always refer to an object that is an instance of a class that 


A compile-time unchecked warning will be given at any invocation of the method above 
because an invocation is considered by the Java programming language's static type system 
to create an array whose element type, List <String>, is non-reifiable (§15.12.4.2). Ifand 
only if the body of the method was type-safe with respect to the variable arity parameter, 
then the programmer could use the SafeVarargs annotation to silence warnings at 
invocations (§9.6.4.7). Since the body of the method as written above causes heap pollution, 
it would be completely inappropriate to use the annotation to disable warnings for callers. 


Finally, note that the st ringLists array could be aliased through variables of types other 
than Object [], and heap pollution could still occur. For example, the type of the array 
variable could be java.util.Collection[] - araw element type - and the body of the 
method above would compile without warnings or errors and still cause heap pollution. And 
if the Java SE Platform defined, say, Sequence as a non-generic supertype of List<T>, 
then using Sequence as the type of array would also cause heap pollution. 


represents the parameterized type. 


The value of 1s in the example above is always an instance of a class that provides a 
representation of a List. 


Assignment from an expression of a raw type to a variable of a parameterized type should 
only be used when combining legacy code which does not make use of parameterized types 
with more modern code that does. 


If no operation that requires a compile-time unchecked warning to be issued takes place, 
and no unsafe aliasing occurs of array variables with non-reifiable element types, then 
heap pollution cannot occur. Note that this does not imply that heap pollution only occurs 
if a compile-time unchecked warning actually occurred. It is possible to run a program 
where some of the binaries were produced by a compiler for an older version of the Java 
programming language, or from sources that explicitly suppressed unchecked warnings. 
This practice is unhealthy at best. 


Conversely, it is possible that despite executing code that could (and perhaps did) 
give rise to a compile-time unchecked warning, no heap pollution takes place. Indeed, 
good programming practice requires that the programmer satisfy herself that despite any 
unchecked warning, the code is correct and heap pollution will not occur. 


4.12.3 Kinds of Variables 


There are eight kinds of variables: 


1. 


A class variable is a field declared using the keyword static within a class 
declaration (§8.3.1.1), or with or without the keyword static within an 


interface declaration (§9.3). 


A class variable is created when its class or interface is prepared (§12.3.2) and 
is initialized to a default value (§4.12.5). The class variable effectively ceases 


to exist when its class or interface is unloaded (§12.7). 


Variables 
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2. Aninstance variable is a field declared within a class declaration without using 
the keyword static (§8.3.1.1). 


If aclass rhas a field a that is an instance variable, then a new instance variable 
a is created and initialized to a default value (§4.12.5) as part of each newly 
created object of class r or of any class that is a subclass of r (§8.1.4). The 
instance variable effectively ceases to exist when the object of which it is a field 
is no longer referenced, after any necessary finalization of the object ($12.6) 
has been completed. 


3. Array components are unnamed variables that are created and initialized to 
default values (§4.12.5) whenever a new object that is an array is created ($10 
(Arrays), §15.10.2). The array components effectively cease to exist when the 
array is no longer referenced. 


4. Method parameters (§8.4.1) name argument values passed to a method. 


For every parameter declared in a method declaration, a new parameter variable 
is created each time that method is invoked (§15.12). The new variable is 
initialized with the corresponding argument value from the method invocation. 
The method parameter effectively ceases to exist when the execution of the 
body of the method is complete. 


5. Constructor parameters (§8.8.1) name argument values passed to a 
constructor. 


For every parameter declared in a constructor declaration, a new parameter 
variable is created each time a class instance creation expression (§15.9) or 
explicit constructor invocation (§8.8.7) invokes that constructor. The new 
variable is initialized with the corresponding argument value from the creation 
expression or constructor invocation. The constructor parameter effectively 
ceases to exist when the execution of the body of the constructor is complete. 


6. Lambda parameters (§15.27.1) name argument values passed to a lambda 
expression body (§15.27.2). 


For every parameter declared in a lambda expression, a new parameter variable 
is created each time a method implemented by the lambda body is invoked 
($15.12). The new variable is initialized with the corresponding argument 
value from the method invocation. The lambda parameter effectively ceases to 
exist when the execution of the lambda expression body is complete. 


7. An exception parameter is created each time an exception is caught by a catch 
clause of a try statement (§14.20). 
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The new variable is initialized with the actual object associated with the 
exception ($11.3, $14.18). The exception parameter effectively ceases to exist 
when execution of the block associated with the catch clause is complete. 


Local variables are declared by local variable declaration statements (§14.4). 


Whenever the flow of control enters a block ($14.2) or for statement 
(§14.14), a new variable is created for each local variable declared in a local 
variable declaration statement immediately contained within that block or for 
statement. 


A local variable declaration statement may contain an expression which 
initializes the variable. The local variable with an initializing expression is not 
initialized, however, until the local variable declaration statement that declares 
it is executed. (The rules of definite assignment (§16 (Definite Assignment)) 
prevent the value of a local variable from being used before it has been 
initialized or otherwise assigned a value.) The local variable effectively ceases 
to exist when the execution of the block or for statement is complete. 


Were it not for one exceptional situation, a local variable could always be regarded 
as being created when its local variable declaration statement is executed. The 
exceptional situation involves the switch statement ($14.11), where it is possible for 
control to enter a block but bypass execution of a local variable declaration statement. 
Because of the restrictions imposed by the rules of definite assignment (§16 (Definite 
Assignment)), however, the local variable declared by such a bypassed local variable 
declaration statement cannot be used before it has been definitely assigned a value by 
an assignment expression (§15.26). 


Example 4.12.3-1. Different Kinds of Variables 


class Point { 


static int numPoints; // numPoints is a class variable 
TN ep yy // x and y are instance variables 
int[] w = new int[10]; // w[0] is an array component 

int setX(int x) { // x is a method parameter 


int oldx = this.x; // oldx is a local variable 
this.x = x; 
return oldx; 


4.12.4 £inal Variables 


A variable can be declared final. A final variable may only be assigned to once. 
It is a compile-time error if a final variable is assigned to unless it is definitely 


unassigned immediately prior to the assignment (§16 (Definite Assignment)). 
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Once a final variable has been assigned, it always contains the same value. If a 
final variable holds a reference to an object, then the state of the object may be 
changed by operations on the object, but the variable will always refer to the same 
object. This applies also to arrays, because arrays are objects; if a final variable 
holds a reference to an array, then the components of the array may be changed by 
operations on the array, but the variable will always refer to the same array. 


A blank final is a final variable whose declaration lacks an initializer. 


A constant variable is a final variable of primitive type or type String that is 
initialized with a constant expression (§15.28). Whether a variable is a constant 
variable or not may have implications with respect to class initialization (§$12.4.1), 
binary compatibility (§13.1), reachability ($14.21), and definite assignment 
($16.1.1). 


Three kinds of variable are implicitly declared final: a field of an interface 
(§9.3), a local variable declared as a resource of a try-with-resources statement 
(§14.20.3), and an exception parameter of a multi-catch clause (§14.20). An 
exception parameter of a uni-catch clause is never implicitly declared final, but 
may be effectively final. 


Example 4.12.4-1. Final Variables 


Declaring a variable final can serve as useful documentation that its value will not change 
and can help avoid programming errors. In this program: 


class Point { 
int x, y; 
int useCount; 
Point (int x, int y) { this.x = x; this.y = y; } 
static final Point origin = new Point(0, 0); 


} 


the class Point declares a final class variable origin. The origin variable holds a 
reference to an object that is an instance of class Point whose coordinates are (0, 0). The 
value of the variable Point .origin can never change, so it always refers to the same 
Point object, the one created by its initializer. However, an operation on this Point object 
might change its state - for example, modifying its useCount or even, misleadingly, its x 
or y coordinate. 


Certain variables that are not declared final are instead considered effectively 
final: 


¢ A local variable whose declarator has an initializer (§14.4.2) is effectively final 
if all of the following are true: 


— It is not declared final. 
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— It never occurs as the left hand side in an assignment expression ($15.26). 
(Note that the local variable declarator containing the initializer is not an 
assignment expression.) 


— It never occurs as the operand of a prefix or postfix increment or decrement 
operator (§15.14, $15.15). 


¢ A local variable whose declarator lacks an initializer is effectively final if all of 
the following are true: 


— It is not declared final. 


— Whenever it occurs as the left hand side in an assignment expression, it is 
definitely unassigned and not definitely assigned before the assignment; that 
is, it is definitely unassigned and not definitely assigned after the right hand 
side of the assignment expression ($16 (Definite Assignment)). 


— It never occurs as the operand of a prefix or postfix increment or decrement 
operator. 


¢« A method, constructor, lambda, or exception parameter (§8.4.1, §8.8.1, §9.4, 
§15.27.1, §14.20) is treated, for the purpose of determining whether it is 
effectively final, as a local variable whose declarator has an initializer. 


If a variable is effectively final, adding the final modifier to its declaration will 
not introduce any compile-time errors. Conversely, a local variable or parameter 
that is declared final in a valid program becomes effectively final if the final 
modifier is removed. 


4.12.5 Initial Values of Variables 


Every variable in a program must have a value before its value is used: 


¢ Each class variable, instance variable, or array component is initialized with a 
default value when it is created (§15.9, §15.10.2): 


— For type byte, the default value is zero, that is, the value of (byte) 0. 

— For type short, the default value is zero, that is, the value of (short) 0. 
— For type int, the default value is zero, that is, 0. 

— For type long, the default value is zero, that is, ou. 

— For type float, the default value is positive zero, that is, 0.0¢. 


— For type double, the default value is positive zero, that is, 0. 0d. 
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— For type char, the default value is the null character, that is, '\u0000'. 
— For type boolean, the default value is false. 
— For all reference types (§4.3), the default value is null. 


e Each method parameter (§8.4.1) is initialized to the corresponding argument 
value provided by the invoker of the method ($15.12). 


¢ Each constructor parameter (§8.8.1) is initialized to the corresponding argument 
value provided by a class instance creation expression ($15.9) or explicit 
constructor invocation (§8.8.7). 


e An exception parameter ($14.20) is initialized to the thrown object representing 
the exception (§11.3, §14.18). 


¢ A local variable (§14.4, §14.14) must be explicitly given a value before it is 
used, by either initialization ($14.4) or assignment (§ 15.26), in a way that can be 
verified using the rules for definite assignment (§16 (Definite Assignment)). 


Example 4.12.5-1. Initial Values of Variables 


class Point { 
static int npoints; 
int x, y; 
Point root; 


} 


class Test { 
public static void main(String[] args) { 
System.out.println("npoints=" + Point.npoints); 
Point p = new Point (); 
System.out.printlin("p.x=" + p.x + ", p.y=" + p.y); 
System.out.println("p.root=" + p.root); 


} 
This program prints: 


npoints=0 
p.x=0, p.y=0 
p.root=null 


illustrating the default initialization of npoints, which occurs when the class Point is 
prepared (§ 12.3.2), and the default initialization of x, y, and root, which occurs when anew 
Point is instantiated. See §12 (Execution) for a full description of all aspects of loading, 
linking, and initialization of classes and interfaces, plus a description of the instantiation 
of classes to make new class instances. 
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4.12.6 Types, Classes, and Interfaces 


In the Java programming language, every variable and every expression has a type 
that can be determined at compile time. The type may be a primitive type or a 
reference type. Reference types include class types and interface types. Reference 
types are introduced by type declarations, which include class declarations (§8.1) 
and interface declarations ($9.1). We often use the term type to refer to either a 
class or an interface. 


In the Java Virtual Machine, every object belongs to some particular class: the class 
that was mentioned in the creation expression that produced the object (§15.9), or 
the class whose Class object was used to invoke a reflective method to produce the 
object, or the st ring class for objects implicitly created by the string concatenation 
operator + ($15.18.1). This class is called the class of the object. An object is said 
to be an instance of its class and of all superclasses of its class. 


Every array also has a class. The method getclass, when invoked for an array 
object, will return a class object (of class class) that represents the class of the 
array (§10.8). 


The compile-time type of a variable is always declared, and the compile-time type 
of an expression can be deduced at compile time. The compile-time type limits the 
possible values that the variable can hold at run time or the expression can produce 
at run time. If a run-time value is a reference that is not nu11, it refers to an object 
or array that has a class, and that class will necessarily be compatible with the 
compile-time type. 


Even though a variable or expression may have a compile-time type that is an 
interface type, there are no instances of interfaces. A variable or expression whose 
type is an interface type can reference any object whose class implements (§8.1.5) 
that interface. 


Sometimes a variable or expression is said to have a "run-time type”. This refers 
to the class of the object referred to by the value of the variable or expression at 
run time, assuming that the value is not null. 


The correspondence between compile-time types and run-time types is incomplete 
for two reasons: 


1. Atrun time, classes and interfaces are loaded by the Java Virtual Machine using 
class loaders. Each class loader defines its own set of classes and interfaces. 
AS a result, it is possible for two loaders to load an identical class or interface 
definition but produce distinct classes or interfaces at run time. Consequently, 
code that compiled correctly may fail at link time if the class loaders that load 
it are inconsistent. 
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See the paper Dynamic Class Loading in the Java Virtual Machine, by Sheng Liang 
and Gilad Bracha, in Proceedings of OOPSLA '98, published as ACM SIGPLAN 
Notices, Volume 33, Number 10, October 1998, pages 36-44, and The Java Virtual 
Machine Specification, Java SE 12 Edition for more details. 


2. Type variables (§4.4) and type arguments (§4.5.1) are not reified at run 
time. As a result, the same class or interface at run time represents multiple 
parameterized types (§4.5) from compile time. Specifically, all compile-time 
parameterizations of a given generic type (§8.1.2, §9.1.2) share a single run- 
time representation. 


Under certain conditions, it is possible that a variable of a parameterized type refers 
to an object that is not of that parameterized type. This situation is known as heap 
pollution (§4.12.2). The variable will always refer to an object that is an instance of 
a class that represents the parameterized type. 


Example 4.12.6-1. Type of a Variable versus Class of an Object 


interface Colorable { 
void setColor(byte r, byte g, byte b); 
} 


class Point { int x, y; } 


class ColoredPoint extends Point implements Colorable { 
byte r, g, b; 
public void setColor(byte rv, byte gv, byte bv) { 
r= rv; g = gv; b = bv; 
} 
} 


class Test { 
public static void main(String[] args) { 
Point p = new Point(); 
ColoredPoint cp = new ColoredPoint (); 
Pp = cp; 
Colorable c = cp; 


In this example: 
¢ The local variable p of the method main of class Test has type Point and is initially 
assigned a reference to a new instance of class Point. 


¢ The local variable cp similarly has as its type ColoredPoint, and is initially assigned 
a reference to a new instance of class ColoredPoint. 


¢ The assignment of the value of cp to the variable p causes p to hold a reference 
to a ColoredPoint object. This is permitted because ColoredPoint is a subclass 
of Point, so the class ColoredPoint is assignment-compatible (§5.2) with the type 
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Point. A ColoredPoint object includes support for all the methods of a Point. In 
addition to its particular fields r, g, and b, it has the fields of class Point, namely x and y. 


¢ The local variable c has as its type the interface type Colorable, so it can hold a 
reference to any object whose class implements Colorable; specifically, it can hold a 
reference to a ColoredPoint. 


Note that an expression such as new Colorable() is not valid because it is not possible 
to create an instance of an interface, only of a class. However, the expression new 
Colorable() { public void setColor... } is valid because it declares an 
anonymous class (§15.9.5) that implements the Colorab1le interface. 
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Every expression written in the Java programming language either produces no 
result ($15.1) or has a type that can be deduced at compile time ($15.3). When an 
expression appears in most contexts, it must be compatible with a type expected in 
that context; this type is called the target type. For convenience, compatibility of 
an expression with its surrounding context is facilitated in two ways: 


¢ First, for some expressions, termed poly expressions (§15.2), the deduced type 
can be influenced by the target type. The same expression can have different 
types in different contexts. 


¢ Second, after the type of the expression has been deduced, an implicit conversion 
from the type of the expression to the target type can sometimes be performed. 


If neither strategy is able to produce the appropriate type, a compile-time error 
occurs. 


The rules determining whether an expression is a poly expression, and if so, its type 
and compatibility in a particular context, vary depending on the kind of context and 
the form of the expression. In addition to influencing the type of the expression, 
the target type may in some cases influence the run time behavior of the expression 
in order to produce a value of the appropriate type. 


Similarly, the rules determining whether a target type allows an implicit conversion 
vary depending on the kind of context, the type of the expression, and, in one special 
case, the value of a constant expression ($15.28). A conversion from type s to type 
T allows an expression of type s to be treated at compile time as if it had type r 
instead. In some cases this will require a corresponding action at run time to check 
the validity of the conversion or to translate the run-time value of the expression 
into a form appropriate for the new type T. 
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Example 5.0-1. Conversions at Compile Time and Run Time 


¢ Aconversion from type Object to type Thread requires a run-time check to make sure 
that the run-time value is actually an instance of class Thread or one of its subclasses; 
if it is not, an exception is thrown. 


¢ A conversion from type Thread to type Object requires no run-time action; Thread 
is a subclass of Ob ject, so any reference produced by an expression of type Thread is 
a valid reference value of type Object. 


¢ Aconversion from type int to type long requires run-time sign-extension of a 32-bit 
integer value to the 64-bit Long representation. No information is lost. 


¢ Aconversion from type double to type long requires a non-trivial translation from a 
64-bit floating-point value to the 64-bit integer representation. Depending on the actual 
run-time value, information may be lost. 


The conversions possible in the Java programming language are grouped into 
several broad categories: 


¢ Identity conversions 

¢ Widening primitive conversions 
e Narrowing primitive conversions 
e Widening reference conversions 
¢ Narrowing reference conversions 
¢ Boxing conversions 


¢ Unboxing conversions 


¢ Unchecked conversions 
¢ Capture conversions 

e String conversions 

e Value set conversions 


There are six kinds of conversion contexts in which poly expressions may be 
influenced by context or implicit conversions may occur. Each kind of context has 
different rules for poly expression typing and allows conversions in some of the 
categories above but not others. The contexts are: 


¢ Assignment contexts (§5.2, $15.26), in which an expression's value is bound to 
a named variable. Primitive and reference types are subject to widening, values 
may be boxed or unboxed, and some primitive constant expressions may be 
subject to narrowing. An unchecked conversion may also occur. 


CONVERSIONS AND CONTEXTS 


¢ Strict invocation contexts (§5.3, §15.9, §15.12), in which an argument is bound 
to a formal parameter of a constructor or method. Widening primitive, widening 
reference, and unchecked conversions may occur. 


¢ Loose invocation contexts (§5.3, §15.9, $15.12), in which, like strict invocation 
contexts, an argument is bound to a formal parameter. Method or constructor 
invocations may provide this context if no applicable declaration can be found 
using only strict invocation contexts. In addition to widening and unchecked 
conversions, this context allows boxing and unboxing conversions to occur. 


¢ String contexts ($5.4, §15.18.1), in which a value of any type is converted to an 
object of type string. 


¢ Casting contexts ($5.5), in which an expression's value is converted to a type 
explicitly specified by a cast operator ($15.16). Casting contexts are more 
inclusive than assignment or loose invocation contexts, allowing any specific 
conversion other than a string conversion, but certain casts to a reference type 
are checked for correctness at run time. 


¢ Numeric contexts ($5.6), in which the operands of a numeric operator may be 
widened to a common type so that an operation can be performed. 


The term "conversion" is also used to describe, without being specific, any 
conversions allowed in a particular context. For example, we say that an expression 
that is the initializer of a local variable is subject to "assignment conversion", 
meaning that a specific conversion will be implicitly chosen for that expression 
according to the rules for the assignment context. 


Example 5.0-2. Conversions In Various Contexts 


class Test { 
public static void main(String[] args) { 
// Casting conversion (5.4) of a float literal to 
// type int. Without the cast operator, this would 
// be a compile-time error, because this is a 
// narrowing conversion (5.1.3): 
int i = (int)12.5f; 


// String conversion (5.4) of i's int value: 
System.out.printin("(int)12.5f==" + i); 


// Assignment conversion (5.2) of i's value to type 
// float. This is a widening conversion (5.1.2): 


float f = i; 


// String conversion of f's float value: 
System.out.println("after float widening: " + f); 


// Numeric promotion (5.6) of i's value to type 
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// float. This is a binary numeric promotion. 

// After promotion, the operation is float*float: 
System.out.print (f); 

f Shi 0e iF 


// Two string conversions of i and f: 
System.out.printlin("*" + i + "==" + f); 


// Invocation conversion (5.3) of f's value 

// to type double, needed because the method Math.sin 
// accepts only a double argument: 

double d = Math.sin(f); 


// Two string conversions of f and d: 
System.out.println("Math.sin(" + f + ")==" + da); 


This program produces the output: 


(int) 12.5f==12 

after float widening: 12.0 
12.0*12==144.0 

Math.sin (144.0) ==-0.49102159389846934 


5.1 Kinds of Conversion 


Specific type conversions in the Java programming language are divided into 13 
categories. 


5.1.1 Identity Conversion 


A conversion from a type to that same type is permitted for any type. 


This may seem trivial, but it has two practical consequences. First, it is always permitted 
for an expression to have the desired type to begin with, thus allowing the simply stated rule 
that every expression is subject to conversion, if only a trivial identity conversion. Second, 
it implies that it is permitted for a program to include redundant cast operators for the sake 
of clarity. 


5.1.2 Widening Primitive Conversion 


19 specific conversions on primitive types are called the widening primitive 
conversions: 


* byte tO short, int, long, float, Or double 


CONVERSIONS AND CONTEXTS Kinds of Conversion 


* short to int, long, float, Or double 
* char tO int, long, float, Or double 
* int tO long, float, Or double 


* long to float or double 


* float to double 


A widening primitive conversion does not lose information about the overall 
magnitude of a numeric value in the following cases, where the numeric value is 
preserved exactly: 


¢ from an integral type to another integral type 

¢ from byte, short, or char to a floating point type 

¢ from int to double 

¢ from float tO double ina strict fp expression (§15.4) 


A widening primitive conversion from float to double that is not strict fp may 
lose information about the overall magnitude of the converted value. 


A widening primitive conversion from int to float, or from long to float, or 
from long to double, may result in loss of precision - that is, the result may lose 
some of the least significant bits of the value. In this case, the resulting floating- 
point value will be a correctly rounded version of the integer value, using [EEE 
754 round-to-nearest mode (§4.2.4). 


A widening conversion of a signed integer value to an integral type rT simply sign- 
extends the two's-complement representation of the integer value to fill the wider 
format. 


A widening conversion of a char to an integral type r zero-extends the 
representation of the char value to fill the wider format. 


Despite the fact that loss of precision may occur, a widening primitive conversion 
never results in a run-time exception (§11.1.1). 


Example 5.1.2-1. Widening Primitive Conversion 


class Test { 
public static void main(String[] args) { 
int big = 1234567890; 
float approx = big; 
System.out.printin(big —- (int) approx); 
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This program prints: 
-46 


thus indicating that information was lost during the conversion from type int to type float 
because values of type float are not precise to nine significant digits. 


5.1.3 Narrowing Primitive Conversion 


22 specific conversions on primitive types are called the narrowing primitive 
conversions: 


* short to byte OF char 

* char tO byte OF short 

* int tO byte, short, Or char 

* long tO byte, short, char, or int 

* float tO byte, short, char, int, Or long 

* double tO byte, short, char, int, long, Or float 


A narrowing primitive conversion may lose information about the overall 
magnitude of a numeric value and may also lose precision and range. 


A natrowing primitive conversion from double to float is governed by the IEEE 
754 rounding rules (§4.2.4). This conversion can lose precision, but also lose range, 
resulting in a float zero from a nonzero double and a float infinity from a finite 
double. A double NaN is converted to a float NaN and a double infinity is 
converted to the same-signed float infinity. 


A narrowing conversion of a signed integer to an integral type rT simply discards 
all but the n lowest order bits, where n is the number of bits used to represent type 
T. In addition to a possible loss of information about the magnitude of the numeric 
value, this may cause the sign of the resulting value to differ from the sign of the 
input value. 


A narrowing conversion of a char to an integral type rT likewise simply discards 
all but the n lowest order bits, where n is the number of bits used to represent type 
T. In addition to a possible loss of information about the magnitude of the numeric 
value, this may cause the resulting value to be a negative number, even though 
chars represent 16-bit unsigned integer values. 


A narrowing conversion of a floating-point number to an integral type T takes two 
steps: 
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1. In the first step, the floating-point number is converted either to a long, if Tis 
long, or to an int, if Tis byte, short, char, or int, as follows: 


¢ If the floating-point number is NaN (§4.2.3), the result of the first step of the 
conversion is an int or long 0. 


¢ Otherwise, if the floating-point number is not an infinity, the floating-point 
value is rounded to an integer value v, rounding toward zero using IEEE 754 
round-toward-zero mode (§4.2.3). Then there are two cases: 


a. If ris long, and this integer value can be represented as a long, then the 
result of the first step is the Long value v. 


b. Otherwise, if this integer value can be represented as an int, then the 
result of the first step is the int value v. 


¢ Otherwise, one of the following two cases must be true: 


a. The value must be too small (a negative value of large magnitude 
or negative infinity), and the result of the first step is the smallest 
representable value of type int or Long. 


b. The value must be too large (a positive value of large magnitude 
or positive infinity), and the result of the first step is the largest 
representable value of type int or Long. 


2. Inthe second step: 
¢ If ris int or long, the result of the conversion is the result of the first step. 


e If Tis byte, char, Or short, the result of the conversion is the result of a 
narrowing conversion to type rT (§5.1.3) of the result of the first step. 


Despite the fact that overflow, underflow, or other loss of information may occur, 
a narrowing primitive conversion never results in a run-time exception (§11.1.1). 


Example 5.1.3-1. Narrowing Primitive Conversion 


class Test { 
public static void main(String[] args) { 
float fmin = Float.NEGATIVE_INFINITY; 
float fmax = Float.POSITIVE_INFINITY; 


System.out.printin("long: " + (long) fmin + 

".." + (long) fmax) ; 
System.out.printlin("int: " + (int)fmin + 

"J." + (int) fmax); 
System.out.println("short: " + (short)fmin + 

"lJ." + (short) fmax) ; 
System.out.println("char: " + (int) (char) fmin + 


"J." + (int) (char) fmax) ; 
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System.out.println("byte: " + (byte)fmin + 
".." + (byte) fmax) ; 


This program produces the output: 


long: -—9223372036854775808. .9223372036854775807 
int: -2147483648..2147483647 

short: 0. =1 

chars 0..65535 

byte: 0..-1 


The results for char, int, and long are unsurprising, producing the minimum and 
maximum representable values of the type. 


The results for byte and short lose information about the sign and magnitude of the 
numeric values and also lose precision. The results can be understood by examining the 
low order bits of the minimum and maximum int. The minimum int is, in hexadecimal, 
0x80000000, and the maximum int is 0x7£ff£f fF. This explains the short results, which 
are the low 16 bits of these values, namely, 0x0000 and Oxf fff; it explains the char results, 
which also are the low 16 bits of these values, namely, '\u0000' and '\uffff'; and it 
explains the byte results, which are the low 8 bits of these values, namely, 0x00 and Oxf f. 


Example 5.1.3-2. Narrowing Primitive Conversions that lose information 


class Test { 
public static void main(String[] args) { 
// A narrowing of int to short loses high bits: 
System.out.printin("(short) 0x12345678==0x" + 


System.out.printin(" (byte) 255=="_+ (byte)255); 

// A float value too big to fit gives largest int value: 
System.out.printin("(int)1le20f==" + (int)1le20f); 

// A NaN converted to int yields zero: 
System.out.printin("(int)NaN=="_+ (int)Float.NaN) ; 

// AK double value too large for float yields infinity: 
System.out.println("(float)—-le1l00==" + (float)-1e100); 

// A double value too small for float underflows to zero: 
System.out.println("(float) le-50==" + (float) 1le-50); 


This program produces the output: 
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Integer.toHexString( (short) 0x12345678) ); 
// An int value too big for byte changes sign and magnitude: 
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(short) 0x12345678==0x5678 
(byte) 255==-1 

(int) 1le20f==2147483647 
(int) NaN== 

(float) -le100==—-Infinity 
(float) le-50==0.0 


5.1.4 Widening and Narrowing Primitive Conversion 


The following conversion combines both widening and narrowing primitive 
conversions: 


* byte tO char 


First, the byte is converted to an int via widening primitive conversion (§5.1.2), 
and then the resulting int is converted to a char by narrowing primitive conversion 
($5.1.3). 


5.1.5 Widening Reference Conversion 


A widening reference conversion exists from any reference type s to any reference 
type r, provided s is a subtype of r (§4.10). 


Widening reference conversions never require a special action at run time and 
therefore never throw an exception at run time. They consist simply in regarding 
a reference as having some other type in a manner that can be proved correct at 
compile time. 


The null type is not a reference type (§4.1), and so a widening reference conversion does not 
exist from the null type to a reference type. However, many conversion contexts explicitly 
allow the null type to be converted to a reference type. 


5.1.6 Narrowing Reference Conversion 


A narrowing reference conversion treats expressions of a reference type s as 
expressions of a different reference type r, where s is not a subtype of T. 
The supported pairs of types are defined in §5.1.6.1. Unlike widening reference 
conversion, the types need not be directly related. However, there are restrictions 
that prohibit conversion between certain pairs of types when it can be statically 
proven that no value can be of both types. 


A narrowing reference conversion may require a test at run time to validate 
that a value of type s is a legitimate value of type 7. However, due to the 
lack of parameterized type information at run time, some conversions cannot be 
fully validated by a run time test; they are flagged at compile time (§5.1.6.2). 
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For conversions that can be fully validated by a run time test, and for certain 
conversions that involve parameterized type information but can still be partially 
validated at run time, a ClassCastException is thrown if the test fails (§5.1.6.3). 


5.1.6.1 Allowed Narrowing Reference Conversion 


A narrowing reference conversion exists from reference type s to reference type T 
if all of the following are true: 


* sis not a subtype of r ($4.10) 


¢ If there exists a parameterized type x that is a supertype of 7, and a parameterized 
type y that is a supertype of s, such that the erasures of x and y are the same, then 
Xand y are not provably distinct ($4.5). 


Using types from the java.util package as an example, no narrowing reference 
conversion exists from ArrayList<String> to ArrayList<Object>, or vice versa, 
because the type arguments String and Object are provably distinct. For the 
same reason, no narrowing reference conversion exists from ArrayList<String> to 
List<Object>, or vice versa. The rejection of provably distinct types is a simple static 
gate to prevent "stupid" narrowing reference conversions. 


¢ One of the following cases applies: 


1. 
2. 


sand rare class types, and either |s| <: |7| or |7| <: |s|. 
sand T are interface types. 


sis aclass type, T is an interface type, and s does not name a final class 


(§8.1.1). 


s is a class type, T is an interface type, and s names a final class that 
implements the interface named by r. 


sis an interface type, Tis a class type, and r does not name a final class. 


s is an interface type, T is a class type, and T names a final class that 
implements the interface named by s. 


sis the class type Object or the interface type java.io.Serializable or 
Cloneable (the only interfaces implemented by arrays ($10.8)), and ris an 
array type. 


Sis an array type sc[J, that is, an array of components of type sc; Tis an 
array type Tc[], that is, an array of components of type rc; and a narrowing 
reference conversion exists from sc to Tc. 


sis a type variable, and a narrowing reference conversion exists from the 
upper bound of s to r. 
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10. r is a type variable, and either a widening reference conversion or a 
narrowing reference conversion exists from s to the upper bound of rT. 


11. sis an intersection type s; « ... & S,, and for alli (1 <i<zn), either a widening 
reference conversion or a narrowing reference conversion exists from s; to T. 


12. ris an intersection type T, « ... & T,, and for alli (1 <i<7n), either a widening 
reference conversion or a narrowing reference conversion exists from sto T:. 


5.1.6.2. Checked and Unchecked Narrowing Reference Conversions 


A narrowing reference conversion is either checked or unchecked. These terms 
refer to the ability of the Java Virtual Machine to validate, or not, the type 
correctness of the conversion. 


If a narrowing reference conversion is unchecked, then the Java Virtual Machine 
will not be able to fully validate its type correctness, possibly leading to heap 
pollution (§4.12.2). To flag this to the programmer, an unchecked narrowing 
reference conversion causes a compile-time unchecked warning, unless suppressed 
by @SuppressWarnings (§9.6.4.5). In contrast, if a narrowing reference conversion 
is not unchecked, then it is checked; the Java Virtual Machine will be able to fully 
validate its type correctness, so no warning is given at compile time. 


The unchecked narrowing reference conversions are as follows: 


e A narrowing reference conversion from a type s to a parameterized class or 
interface type Tis unchecked, unless at least one of the following is true: 


— All of the type arguments of r are unbounded wildcards. 


— T<: S,and s has no subtype x other than r where the type arguments of x are 
not contained in the type arguments of rT. 


¢ A narrowing reference conversion from a type s to a type variable ris unchecked. 


¢ A narrowing reference conversion from a type s to an intersection type T, & ... & 
T, is unchecked if there exists a T; (1 <i <n) such that sis not a subtype of 1, 
and a narrowing reference conversion from s to T; is unchecked. 


5.1.6.3 Narrowing Reference Conversions at Run Time 


All checked narrowing reference conversions require a validity check at run 
time. Primarily, these conversions are to class and interface types that are not 
parameterized. 
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Some unchecked narrowing reference conversions require a validity check at run 
time. This depends on whether the unchecked narrowing reference conversion is 
completely unchecked or partially unchecked. A partially unchecked narrowing 
reference conversion requires a validity check at run time, while a completely 


unchecked narrowing reference conversion does not. 


The categorization of an unchecked narrowing reference conversion is as follows: 


The run time validity check for a checked or partially unchecked narrowing 


These terms refer to the compatibility of the types involved in the conversion when 
viewed as raw types. If the conversion is conceptually an "upcast", then the conversion 
is completely unchecked; no run time test is needed because the conversion is legal in 
the non-generic type system of the Java Virtual Machine. In contrast, if the conversion is 
conceptually a "downcast", then the conversion is partially unchecked; even in the non- 
generic type system of the Java Virtual Machine, a run time check is needed to test the 
compatibility of the (raw) types involved in the conversion. 


Using types from the java.util package as an example, a conversion from 
ArrayList<String> to Collection<T> is completely unchecked, because the (raw) 
type ArrayList is a subtype of the (raw) type Collection in the Java Virtual Machine. 
In contrast, a conversion from Collection<T> to ArrayList<String> is partially 
unchecked, because the (raw) type Collection is not a subtype of the (raw) type 
ArrayList in the Java Virtual Machine. 


An unchecked narrowing reference conversion from s to a non-intersection type 


Tis completely unchecked if |s| <: |7]. 


Otherwise, it is partially unchecked. 


An unchecked narrowing reference conversion from s to an intersection type T; 
& ... & T, is completely unchecked if, for all i (1 <i <n), either s <: T; ora 
narrowing reference conversion from s to T; is completely unchecked. 


Otherwise, it is partially unchecked. 


reference conversion is as follows: 


e If the value at run time is nu11, then the conversion is allowed. 


¢ Otherwise, let R be the class of the object referred to by the value, and let r be 
the erasure ($4.6) of the type being converted to. Then: 


— If Ris an ordinary class (not an array class): 


>» If ris a class type, then R must be either the same class as r (§4.3.4) or a 


subclass of rT, or a ClassCastException is thrown. 


>» If ris an interface type, then R must implement interface r (§8.1.5), or a 


ClassCastException is thrown. 
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> If ris an array type, then a ClassCastException is thrown. 


— If Ris an interface: 


Note that R cannot be an interface when these rules are first applied for any given 
conversion, but R may be an interface if the rules are applied recursively because the 
run-time reference value may refer to an array whose element type is an interface type. 


>» If r is a class type, then r must be object (§4.3.2), or a 
ClassCastException is thrown. 


>» If ris an interface type, then R must be either the same interface as Tora 
subinterface of T, or a ClassCastException is thrown. 


>» If ris an array type, then a ClassCastException is thrown. 


— If Ris aclass representing an array type Rc[], that is, an array of components 
of type Rc: 


>» If r is a class type, then r must be object (84.3.2), or a 
ClassCastException is thrown. 


>» If ris an interface type, then r must be the type java.io.Serializable 
Or Cloneable (the only interfaces implemented by arrays), or a 
ClassCastException 1s thrown. 


>» If ris an array type Tc[], that is, an array of components of type rc, then 
a ClassCastException is thrown unless either rc and rc are the same 
primitive type, or Tc and Rc are reference types and are allowed by a 
recursive application of these run-time rules. 


If the conversion is to an intersection type T; & ... & T,, then for alli(1 <i<n), 
any run-time check required for a conversion from s to T; is also required for the 
conversion to the intersection type. 


5.1.7. Boxing Conversion 


Boxing conversion treats expressions of a primitive type as expressions of a 
corresponding reference type. Specifically, the following nine conversions are 
called the boxing conversions: 


¢ From type boolean to type Boolean 
¢ From type byte to type Byte 


¢ From type short to type Short 
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From type char to type Character 
From type int to type Integer 
From type long to type Long 
From type float to type Float 
From type double to type Double 


From the null type to the null type 


This rule is necessary because the conditional operator ($15.25) applies boxing 
conversion to the types of its operands, and uses the result in further calculations. 


At run time, boxing conversion proceeds as follows: 


If pis a value of type boolean, then boxing conversion converts p into a reference 
r Of class and type Boolean, such that r.booleanValue() == 


If p is a value of type byte, then boxing conversion converts p into a reference 
r of class and type Byte, such that r.byteValue() == p 


If p is a value of type char, then boxing conversion converts p into a reference 
r Of class and type Character, such that r.charValue() == p 


If pis a value of type short, then boxing conversion converts p into a reference 
r Of class and type Short, such that r.shortValue() == p 


If p is a value of type int, then boxing conversion converts p into a reference r 
of class and type Integer, such that r.intvalue() == p 


If p is a value of type long, then boxing conversion converts p into a reference 
r of class and type Long, such that r.longValue() == p 


If pis a value of type float then: 


— If pis not NaN, then boxing conversion converts p into a reference r of class 
and type Float, such that r.floatValue() evaluates to p 


— Otherwise, boxing conversion converts p into a reference r of class and type 
Float such that r.isNan() evaluates to true 


If pis a value of type double, then: 


— If pis not NaN, boxing conversion converts p into a reference r of class and 
type Double, such that r.doubleValue () evaluates to p 


— Otherwise, boxing conversion converts p into a reference r of class and type 
Double such that r.isNaNn() evaluates to true 
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¢ If pis a value of any other type, boxing conversion is equivalent to an identity 
conversion (§5.1.1). 


If the value p being boxed is the result of evaluating a constant expression (§15.28) 
of type boolean, char, short, int, OF long, and the result is true, false, a 
character in the range '\u0000' to '\u007£' inclusive, or an integer in the range 
-128 to 127 inclusive, then let a and b be the results of any two boxing conversions 
of p. It is always the case that a == b. 


Ideally, boxing a primitive value would always yield an identical reference. In practice, this 
may not be feasible using existing implementation techniques. The rule above is a pragmatic 
compromise, requiring that certain common values always be boxed into indistinguishable 
objects. The implementation may cache these, lazily or eagerly. For other values, the rule 
disallows any assumptions about the identity of the boxed values on the programmer's part. 
This allows (but does not require) sharing of some or all of these references. 


This ensures that in most common cases, the behavior will be the desired one, without 
imposing an undue performance penalty, especially on small devices. Less memory-limited 
implementations might, for example, cache all char and short values, as well as int and 
long values in the range of -32K to +32K. 


A boxing conversion may result in an outOfMemoryError if a new instance of one 
of the wrapper classes (Boolean, Byte, Character, Short, Integer, Long, Float, 
Or Double) needs to be allocated and insufficient storage is available. 


5.1.8 Unboxing Conversion 


Unboxing conversion treats expressions of a reference type as expressions of a 
corresponding primitive type. Specifically, the following eight conversions are 
called the unboxing conversions: 


¢ From type Boolean to type boolean 
¢ From type Byte to type byte 

¢ From type Short to type short 

¢ From type Character to type char 
¢ From type Integer to type int 

¢ From type Long to type long 

¢ From type Float to type float 

¢ From type Double to type double 


At run time, unboxing conversion proceeds as follows: 
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e If ris a reference of type Boolean, then unboxing conversion converts r into 


r.booleanValue () 


¢ If r is a reference of type Byte, then unboxing conversion converts r into 
r.byteValue () 


¢ If ris areference of type Character, then unboxing conversion converts r into 


r.charValue() 


¢ If ris a reference of type Short, then unboxing conversion converts r into 


r.shortValue () 


¢ If ris a reference of type Integer, then unboxing conversion converts r into 


r.intValue() 


e If r is a reference of type Long, then unboxing conversion converts r into 
r.longValue () 


e If r is a reference of type Float, unboxing conversion converts r into 
r.floatValue () 


¢ If ris a reference of type Double, then unboxing conversion converts r into 
r.doubleValue () 


¢ If ris null, unboxing conversion throws a NullPointerException 


A type is said to be convertible to a numeric type if it is anumeric type (§4.2), or it is 
a reference type that may be converted to a numeric type by unboxing conversion. 


A type is said to be convertible to an integral type if it is an integral type, or itis a 
reference type that may be converted to an integral type by unboxing conversion. 


5.1.9 Unchecked Conversion 


Let Gname a generic type declaration with n type parameters. 


There is an unchecked conversion from the raw class or interface type (§4.8) G to 
any parameterized type of the form G<T,...,Tn>. 


There is an unchecked conversion from the raw array type G[] Kto any array type of 
the form G<Ty,...,Tn>[] a (The notation [ ] K indicates an array type of k dimensions.) 


Use of an unchecked conversion causes a compile-time unchecked warning unless 
all type arguments rT; (1 <i <n) are unbounded wildcards (§4.5.1), or the warning 
is suppressed by @SuppressWarnings (§9.6.4.5). 


Unchecked conversion is used to enable a smooth interoperation of legacy code, written 
before the introduction of generic types, with libraries that have undergone a conversion 
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to use genericity (a process we call generification). In such circumstances (most notably, 
clients of the Collections Framework in java.util), legacy code uses raw types (e.g. 
Collection instead of Collection<String>). Expressions of raw types are passed as 
arguments to library methods that use parameterized versions of those same types as the 
types of their corresponding formal parameters. 


Such calls cannot be shown to be statically safe under the type system using generics. 
Rejecting such calls would invalidate large bodies of existing code, and prevent them from 
using newer versions of the libraries. This in turn, would discourage library vendors from 
taking advantage of genericity. To prevent such an unwelcome turn of events, a raw type 
may be converted to an arbitrary invocation of the generic type declaration to which the raw 
type refers. While the conversion is unsound, it is tolerated as a concession to practicality. 
An unchecked warning is issued in such cases. 


5.1.10 Capture Conversion 


Let G name a generic type declaration (§8.1.2, §9.1.2) with n type parameters 
Aj,...,An with corresponding bounds Uj,...,Un. 


There exists a capture conversion from a parameterized type G<Ty,...,T,> ($4.5) to 
a parameterized type G<Sj,...,5,>, where, for 1 <i<n: 


If 7; is a wildcard type argument (§4.5.1) of the form ?, then s; is a fresh type 
variable whose upper bound is U;[4;:=S1, ...,An:=Sn] and whose lower bound 
is the null type ($4.1). 


If r,; is a wildcard type argument of the form ? extends B;, then s; is a fresh 
type variable whose upper bound is glb(8;, U;[A1:=S1, ...,An:=Sn]) and whose 
lower bound is the null type. 


glb(Vz,...,Vm) 18 defined as Vv, & ... & Vin 


It is a compile-time error if, for any two classes (not interfaces) vi and vj, Vv; is 
not a subclass of v, or vice versa. 


If r; is a wildcard type argument of the form ? super B:, then s; is a fresh type 
variable whose upper bound is U;[4;:=S1, ...,An:=Sn] and whose lower bound 
iS B;. 


Otherwise, $s; = T;. 


Capture conversion on any type other than a parameterized type ($4.5) acts as an 
identity conversion (§5.1.1). 


Capture conversion is not applied recursively. 


Capture conversion never requires a special action at run time and therefore never 
throws an exception at run time. 
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Capture conversion is designed to make wildcards more useful. To understand the 
motivation, let's begin by looking at the method java.util.Collections.reverse(): 


public static void reverse (List<?> list); 


The method reverses the list provided as a parameter. It works for any type of list, and so the 
use of the wildcard type List <?> as the type of the formal parameter is entirely appropriate. 


Now consider how one would implement reverse (): 


public static void reverse (List<?> list) { rev(list); } 
private static <T> void rev(List<T> list) { 
List<T> tmp = new ArrayList<T>(list); 
for (int i = 0; i < list.size(); itt) { 
list.set(i, tmp.get(list.size() - i- 1)); 


The implementation needs to copy the list, extract elements from the copy, and insert them 
into the original. To do this in a type-safe manner, we need to give a name, T, to the element 
type of the incoming list. We do this in the private service method rev (). This requires us 
to pass the incoming argument list, of type List <?>, as an argument to rev (). In general, 
List<?> isa list of unknown type. It is not a subtype of List <T>, for any type T. Allowing 
such a subtype relation would be unsound. Given the method: 


public static <T> void fill(List<T> 1, T obj) 
the following code would undermine the type system: 


List<String> ls = new ArrayList<String>(); 
List<?> 1 = 1s; 
Collections.fill(l, new Object()); // not legal - but assume it was! 
String s = ls.get(0); // ClassCastException - ls contains 
// Objects, not Strings. 


So, without some special dispensation, we can see that the call from reverse () to rev () 
would be disallowed. If this were the case, the author of reverse () would be forced to 
write its signature as: 


public static <T> void reverse(List<T> list) 


This is undesirable, as it exposes implementation information to the caller. Worse, the 
designer of an API might reason that the signature using a wildcard is what the callers of 
the API require, and only later realize that a type safe implementation was precluded. 


The call from reverse() to rev() is in fact harmless, but it cannot be justified on the 
basis of a general subtyping relation between List <?> and List<T>. The call is harmless, 
because the incoming argument is doubtless a list of some type (albeit an unknown one). If 
we can capture this unknown type in a type variable x, we can infer T to be x. That is the 
essence of capture conversion. The specification of course must cope with complications, 
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like non-trivial (and possibly recursively defined) upper or lower bounds, the presence of 
multiple arguments etc. 


Mathematically sophisticated readers will want to relate capture conversion to established 
type theory. Readers unfamiliar with type theory can skip this discussion - or else study a 
suitable text, such as Types and Programming Languages by Benjamin Pierce, and then 
revisit this section. 


Here then is a brief summary of the relationship of capture conversion to established 
type theoretical notions. Wildcard types are a restricted form of existential types. Capture 
conversion corresponds loosely to an opening of a value of existential type. A capture 
conversion of an expression e can be thought of as an open of e in a scope that comprises 
the top level expression that encloses e. 


The classical open operation on existentials requires that the captured type variable must 
not escape the opened expression. The open that corresponds to capture conversion is 
always on a scope sufficiently large that the captured type variable can never be visible 
outside that scope. The advantage of this scheme is that there is no need for a close 
operation, as defined in the paper On Variance-Based Subtyping for Parametric Types by 
Atsushi Igarashi and Mirko Viroli, in the proceedings of the 16th European Conference on 
Object Oriented Programming (ECOOP 2002). For a formal account of wildcards, see Wild 
FJ by Mads Torgersen, Erik Ernst and Christian Plesner Hansen, in the 12th workshop on 
Foundations of Object Oriented Programming (FOOL 2005). 


5.1.11 String Conversion 


Any type may be converted to type string by string conversion. 


A value x of primitive type T is first converted to a reference value as if by giving 


it as an argument to an appropriate class instance creation expression (§15.9): 
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e If Tis boolean, then use new Boolean (x). 

e If Tis char, then use new Character (x). 

e If ris byte, short, Or int, then use new Integer (x). 

e If ris long, then use new Long (x). 

e If Tis float, then use new Float (x). 

e If Tis double, then use new Double (x). 

This reference value is then converted to type st ring by string conversion. 


Now only reference values need to be considered: 


¢ Ifthe reference is nu11, it is converted to the string "nu11" (four ASCII characters 


ns Us; 1). 
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¢ Otherwise, the conversion is performed as if by an invocation of the toString 
method of the referenced object with no arguments; but if the result of invoking 
the toString method is nu11, then the string "nu11" is used instead. 


The toString method is defined by the primordial class Object (§4.3.2). Many 
classes override it, notably Boolean, Character, Integer, Long, Float, Double, 
and String. 


5.1.12 Forbidden Conversions 


Any conversion that is not explicitly allowed is forbidden. 


5.1.13 Value Set Conversion 


Value set conversion is the process of mapping a floating-point value from one 
value set to another without changing its type. 


Within an expression that is not FP-strict ($15.4), value set conversion provides 
choices to an implementation of the Java programming language: 


¢ If the value is an element of the float-extended-exponent value set, then the 
implementation may, at its option, map the value to the nearest element of the 
float value set. This conversion may result in overflow (in which case the value 
is replaced by an infinity of the same sign) or underflow (in which case the value 
may lose precision because it is replaced by a denormalized number or zero of 
the same sign). 


¢ If the value is an element of the double-extended-exponent value set, then the 
implementation may, at its option, map the value to the nearest element of the 
double value set. This conversion may result in overflow (in which case the value 
is replaced by an infinity of the same sign) or underflow (in which case the value 
may lose precision because it is replaced by a denormalized number or zero of 
the same sign). 


Within an FP-strict expression ($15.4), value set conversion does not provide any 
choices; every implementation must behave in the same way: 


¢ If the value is of type float and is not an element of the float value set, then the 
implementation must map the value to the nearest element of the float value set. 
This conversion may result in overflow or underflow. 


¢ If the value is of type double and is not an element of the double value set, then 
the implementation must map the value to the nearest element of the double value 
set. This conversion may result in overflow or underflow. 
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Within an FP-strict expression, mapping values from the float-extended-exponent 
value set or double-extended-exponent value set is necessary only when a method 
is invoked whose declaration is not FP-strict and the implementation has chosen to 
represent the result of the method invocation as an element of an extended-exponent 
value set. 


Whether in FP-strict code or code that is not FP-strict, value set conversion always 
leaves unchanged any value whose type is neither float nor double. 


5.2 Assignment Contexts 


Assignment contexts allow the value of an expression to be assigned ($15.26) to a 
variable; the type of the expression must be converted to the type of the variable. 


Assignment contexts allow the use of one of the following: 

* an identity conversion (§5.1.1) 

* a widening primitive conversion (§5.1.2) 

* a widening reference conversion (§5.1.5) 

¢ a widening reference conversion followed by an unboxing conversion 


¢ a widening reference conversion followed by an unboxing conversion, then 
followed by a widening primitive conversion 


¢ a boxing conversion (§5.1.7) 

¢ a boxing conversion followed by a widening reference conversion 

¢ an unboxing conversion (§5.1.8) 

¢ an unboxing conversion followed by a widening primitive conversion 


If, after the conversions listed above have been applied, the resulting type is a raw 
type ($4.8), an unchecked conversion (§5.1.9) may then be applied. 


In addition, if the expression is a constant expression (§15.28) of type byte, short, 
char, OF int: 


¢ A narrowing primitive conversion may be used if the variable is of type byte, 
short, Or char, and the value of the constant expression is representable in the 
type of the variable. 
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¢ A natrowing primitive conversion followed by a boxing conversion may be used 
if the variable is of type Byte, Short, or Character, and the value of the constant 
expression is representable in the type byte, short, or char respectively. 


The compile-time narrowing of constant expressions means that code such as: 
byte theAnswer = 42; 


is allowed. Without the narrowing, the fact that the integer literal 42 has type int would 
mean that a cast to byte would be required: 


byte theAnswer = (byte)42; // cast is permitted but not required 


Finally, a value of the null type (the null reference is the only such value) may be 
assigned to any reference type, resulting in a null reference of that type. 


It is a compile-time error if the chain of conversions contains two parameterized 
types that are not in the subtype relation (§4.10). 


An example of such an illegal chain would be: 
Integer, Comparable<Integer>, Comparable, Comparable<String> 


The first three elements of the chain are related by widening reference conversion, while 
the last entry is derived from its predecessor by unchecked conversion. However, this is 
not a valid assignment conversion, because the chain contains two parameterized types, 
Comparable<Integer> and Comparable<String>, that are not subtypes. 


If the type of an expression can be converted to the type of a variable by assignment 
conversion, we say the expression (or its value) is assignable to the variable or, 
equivalently, that the type of the expression is assignment compatible with the type 
of the variable. 


If the type of the variable is float or double, then value set conversion (§5.1.13) 
is applied to the value v that is the result of the conversion(s): 


¢ If vis of type float and is an element of the float-extended-exponent value set, 
then the implementation must map v to the nearest element of the float value set. 
This conversion may result in overflow or underflow. 


¢ If vis of type double and is an element of the double-extended-exponent value 
set, then the implementation must map v to the nearest element of the double 
value set. This conversion may result in overflow or underflow. 


The only exceptions that may arise from conversions in an assignment context are: 
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¢ A ClassCastException if, after the conversions above have been applied, the 
resulting value is an object which is not an instance of a subclass or subinterface 
of the erasure ($4.6) of the type of the variable. 


This circumstance can only arise as a result of heap pollution (§4.12.2). In practice, 
implementations need only perform casts when accessing a field or method of an object 
of parameterized type when the erased type of the field, or the erased return type of the 
method, differ from its unerased type. 


¢ An OutOfMemoryError as a result of a boxing conversion. 


¢ A NullPointerException as a result of an unboxing conversion on a null 


reference. 


e An ArrayStoreException in special cases involving array elements or field 
access (§10.5, §15.26.1). 


Example 5.2-1. Assignment for Primitive Types 


class Test { 


public static void main(String[] args) { 


short s = 12; // narrow 12 to short 
float f = s; // widen short to float 
System.out.println("f="_+ f); 

char c = '\u0123'; 

long 1 = c; // widen char to long 


System.out.println("1=0x" + Long.toString(1,16)); 
f£ = 1.238; 

double d = f; // widen float to double 
System.out.printlin("d="_ + d); 


This program produces the output: 


£=12.0 
1=0x123 


d=1.2300000190734863 


The following program, however, produces compile-time errors: 


class Test { 


public static void main(String[] args) { 


short s = 123; 
char c = s; // error: would require cast 
s=c // error: would require cast 


because not all short values are char values, and neither are all char values short values. 
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Example 5.2-2. Assignment for Reference Types 


class Point { int x, y; } 
class Point3D extends Point { int z; } 
interface Colorable { void setColor(int color); } 


class ColoredPoint extends Point implements Colorable { 
int color; 
public void setColor(int color) { this.color = color; } 


class Test { 
public static void main(String[] args) { 

// Assignments to variables of class type: 

Point p = new Point(); 

p = new Point3D(); 
// OK because Point3D is a subclass of Point 

Point3D p3d = p; 
// Error: will require a cast because a Point 
// might not be a Point3D (even though it is, 
// dynamically, in this example.) 


// Assignments to variables of type Object: 


Object o = p; // OK: any object to Object 
int[] a = new int[3]; 
Object o2 = a; // OK: an array to Object 


// Assignments to variables of interface type: 
ColoredPoint cp = new ColoredPoint (); 
Colorable c = cp; 

// OK: ColoredPoint implements Colorable 


// Assignments to variables of array type: 
byte[] b = new byte[4]; 
a=b; 
// Error: these are not arrays of the same primitive type 
Point3D[] p3da = new Point3D[3]; 
Point[] pa = p3da; 
// OK: since we can assign a Point3D to a Point 
p3da = pa; 
// Error: (cast needed) since a Point 
// can't be assigned to a Point3D 


The following test program illustrates assignment conversions on reference values, but fails 
to compile, as described in its comments. This example should be compared to the preceding 
one. 


class Point { int x, y; } 
interface Colorable { void setColor(int color); } 
class ColoredPoint extends Point implements Colorable { 
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int color; 
public void setColor (int 


class Test { 


public static void main(String[] 
new Point(); 
new ColoredPoint (); 


Point p = 
ColoredPoint cp = 


Assignment Contexts 


color) { this.color = color; } 


args) { 


// Okay because ColoredPoint is a subclass of Point: 


P= CP; 


// Okay because ColoredPoint implements Colorable: 


Colorable c = cp; 


// The following cause compile-time errors because 


// we cannot be sure 
// the run-time type 
// necessary for the 
// must be indicated 


they will succeed, depending on 
of p; a run-time check will be 
needed narrowing conversion and 
by including a cast: 


cp = p; // pep might be neither a ColoredPoint 
// nor a subclass of ColoredPoint 
c= "p; // p might not implement Colorable 


Example 5.2-3. Assignment for Array Types 


class Point { int x, y; } 
class ColoredPoint extends Point { int color; } 


class Test { 


public static void main(String[] 


long[] veclong = new 
Object o = veclong; 


Long 1 = veclong; 
short[] vecshort = 
Point[] pvec = 
ColoredPoint[] cpvec 
pvec = cpvec; 

pvec[0] = new Point () 


In this example: 


veclong; 


args) { 
long[100]; 
// okay 


// compile-time error 


// compile-time error 


new Point[100]; 


= new ColoredPoint [100]; 
// okay 

: // okay at compile time, 
// but would throw an 
// exception at run time 
// compile-time error 


¢ The value of veclong cannot be assigned to a Long variable, because Long is a class 
type other than Object. An array can be assigned only to a variable of a compatible 
array type, or to a variable of type Object, Cloneable or java.io.Serializable. 


¢ The value of veclong cannot be assigned to vecshort, because they are arrays of 
primitive type, and short and long are not the same primitive type. 
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¢ The value of cpvec can be assigned to pvec, because any reference that could be the 
value of an expression of type ColoredPoint can be the value of a variable of type 
Point. The subsequent assignment of the new Point to a component of pvec then 
would throw an ArrayStoreException (if the program were otherwise corrected so 
that it could be compiled), because a ColoredPoint array cannot have an instance of 
Point as the value of a component. 


¢ The value of pvec cannot be assigned to cpvec, because not every reference that could 
be the value of an expression of type Point can correctly be the value of a variable of 
type ColoredPoint. If the value of pvec at run time were a reference to an instance of 
Point [], and the assignment to cpvec were allowed, a simple reference to a component 
of cpvec, say, cpvec[0], could return a Point, and a Point is not a ColoredPoint 
Thus to allow such an assignment would allow a violation of the type system. A cast 
may be used (§5.5, §15.16) to ensure that pvec references a ColoredPoint []: 


cpvec = (ColoredPoint[])pvec; // OK, but may throw an 
// exception at run time 


5.3 Invocation Contexts 


Invocation contexts allow an argument value in a method or constructor invocation 
($8.8.7.1, §15.9, $15.12) to be assigned to a corresponding formal parameter. 


Strict invocation contexts allow the use of one of the following: 
* an identity conversion (§5.1.1) 

* a widening primitive conversion (§5.1.2) 

* a widening reference conversion (§5.1.5) 


Loose invocation contexts allow a more permissive set of conversions, because 
they are only used for a particular invocation if no applicable declaration can be 
found using strict invocation contexts. Loose invocation contexts allow the use of 
one of the following: 


* an identity conversion (§5.1.1) 

* a widening primitive conversion (§5.1.2) 

* a widening reference conversion (§5.1.5) 

* a widening reference conversion followed by an unboxing conversion 


¢ a widening reference conversion followed by an unboxing conversion, then 
followed by a widening primitive conversion 


¢ a boxing conversion (§5.1.7) 


¢ a boxing conversion followed by widening reference conversion 
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* an unboxing conversion (§5.1.8) 
¢ an unboxing conversion followed by a widening primitive conversion 


If, after the conversions listed for an invocation context have been applied, the 
resulting type is a raw type (§4.8), an unchecked conversion (§5.1.9) may then be 
applied. 


A value of the null type (the null reference is the only such value) may be assigned 
to any reference type. 


It is a compile-time error if the chain of conversions contains two parameterized 
types that are not in the subtype relation (§4.10). 


If the type of an argument expression is either float or double, then value set 
conversion (§5.1.13) is applied after the conversion(s): 


¢ If an argument value of type float is an element of the float-extended-exponent 
value set, then the implementation must map the value to the nearest element of 
the float value set. This conversion may result in overflow or underflow. 


¢ If an argument value of type double is an element of the double-extended- 
exponent value set, then the implementation must map the value to the nearest 
element of the double value set. This conversion may result in overflow or 
underflow. 


The only exceptions that may arise in an invocation context are: 


¢ AClassCastException if, after the type conversions above have been applied, 
the resulting value is an object which is not an instance of a subclass or 
subinterface of the erasure ($4.6) of the corresponding formal parameter type. 


¢ An OutOfMemoryError as a result of a boxing conversion. 


¢ A NullPointerException as a result of an unboxing conversion on a null 
reference. 


Neither strict nor loose invocation contexts include the implicit narrowing of integer 
constant expressions which is allowed in assignment contexts. The designers of the Java 
programming language felt that including these implicit narrowing conversions would add 
additional complexity to the rules of overload resolution (§15.12.2). 


Thus, the program: 


class Test { 
static int m(byte a, int b) { return atb; } 
static int m(short a, short b) { return a-b; } 
public static void main(String[] args) { 
System.out.println(m(12, 2)); // compile-time error 
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} 


causes a compile-time error because the integer literals 12 and 2 have type int, so neither 
method m matches under the rules of overload resolution. A language that included implicit 
narrowing of integer constant expressions would need additional rules to resolve cases like 
this example. 


5.4 String Contexts 


String contexts apply only to an operand of the binary + operator which is not a 
String when the other operand is a String. 


The target type in these contexts is always string, and a string conversion 
($5.1.11) of the non-string operand always occurs. Evaluation of the + operator 
then proceeds as specified in §15.18.1. 


5.5 Casting Contexts 


Casting contexts allow the operand of a cast expression ($15.16) to be converted to 
the type explicitly named by the cast operator. Compared to assignment contexts 
and invocation contexts, casting contexts allow the use of more of the conversions 
defined in §5.1, and allow more combinations of those conversions. 


If the expression is of a primitive type, then a casting context allows the use of one 
of the following: 


¢ an identity conversion (§5.1.1) 

* a widening primitive conversion (§5.1.2) 

* a narrowing primitive conversion (§5.1.3) 

¢ a widening and narrowing primitive conversion (§5.1.4) 

¢ a boxing conversion (§5.1.7) 

¢ a boxing conversion followed by a widening reference conversion (§5.1.5) 


If the expression is of a reference type, then a casting context allows the use of 
one of the following: 


* an identity conversion (§5.1.1) 


* a widening reference conversion (§5.1.5) 
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* a widening reference conversion followed by an unboxing conversion 


¢ a widening reference conversion followed by an unboxing conversion, then 
followed by a widening primitive conversion 


* a narrowing reference conversion (§5.1.6) 

* a narrowing reference conversion followed by an unboxing conversion 
* an unboxing conversion (§5.1.8) 

¢ an unboxing conversion followed by a widening primitive conversion 


If the expression has the null type, then the expression may be cast to any reference 
type. 


If a casting context makes use of a narrowing reference conversion that is checked 
or partially unchecked (§5.1.6.2, §5.1.6.3), then a run time check will be performed 
on the class of the expression's value, possibly causing a ClassCastException. 
Otherwise, no run time check is performed. 


Value set conversion (§5.1.13) is applied after the type conversion. 


The following tables enumerate which conversions are used in certain casting 
contexts. Each conversion is signified by a symbol: 


¢ - signifies no conversion allowed 

¢ = signifies identity conversion (§5.1.1) 

* @ signifies widening primitive conversion (§5.1.2) 

* 1) signifies narrowing primitive conversion (§5.1.3) 

* wn signifies widening and narrowing primitive conversion (§5.1.4) 
+ ff signifies widening reference conversion (§5.1.5) 

~ J signifies narrowing reference conversion (§5.1.6) 

* @ signifies boxing conversion (§5.1.7) 

* ® signifies unboxing conversion (§5.1.8) 


In the tables, a comma between symbols indicates that a casting context uses one 
conversion followed by another. The type object means any reference type other 
than the eight wrapper classes Boolean, Byte, Short, Character, Integer, Long, 
Float, Double. 
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Table 5.5-A. Casting to primitive types 


To> byte short char int long float double boolean 
From J 

byte eS o on oO oO oO 0) : 
short n = n oO oO o (0) z 
char n n 7 oO o o (0) 7 
int n n n ws @ (0) @ : 
long 7 n n n ms 0) o : 
float n n n n n = o 7 
double n n n n ny nN = 7 
boolean - = = = : - - = 
Byte 3) @,o = ®,o @,o @,o @,o - 
Short - ® - ©,o ©,o ©,o ®,o - 
Character - = ® 8,0 @,0 ®,o ®,o i 
Integer - - = ® @,a 8, KO) 7 
Long - = = = ® @,0 @,o 7 
Float . - = z 7 ® KO) - 
Double - - = . - - @ : 
Boolean = = . . . - 7 ic) 
Object Ke Ke J.® Ke L.® L.@ Le J,@ 
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Table 5.5-B. Casting to reference types 


To—> Byte Short CharacterInteger Long Float Double Boolean Object 
From J 

byte a) - - . - - 2 : aft 
short - @ - 2 - = z E of 
char - - ® = = = = 2 eft 
int - - - ® - = é s ot 
long - - - - ® - 2 & et 
float = - - - 7 ® - 2 oft 
double - - - . - = @ ss oft 
boolean - - - x 2 _ : ® oft 
Byte ee - - - - = é . ~ 
Short - ee - - = - 7 = ry 
Character - a Z 7 = = E v 
Integer - - - ~ 7 - a = , 
Long = - - » a = é, EI * 
Float : - - - - s 7 2 v 
Double - - - FS - = 4 ts a 
Boolean - - - = = = 5 ~ a 
Object J ml Yoedd 4 U . 
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Example 5.5-1. Casting for Reference Types 


class Point { int x, y; } 
interface Colorable { void setColor(int color); } 
class ColoredPoint extends Point implements Colorable { 
int color; 
public void setColor(int color) { this.color = color; } 
} 


final class EndPoint extends Point {} 


class Test { 
public static void main(String[] args) { 

Point p = new Point (); 

ColoredPoint cp = new ColoredPoint (); 

Colorable c; 

// The following may cause errors at run time because 

// we cannot be sure they will succeed; this possibility 

// is suggested by the casts: 

cp = (ColoredPoint)p; // p might not reference an 
// object which is a ColoredPoint 
// or a subclass of ColoredPoint 

c = (Colorable)p; // pep might not be Colorable 

// The following are incorrect at compile time because 

// they can never succeed as explained in the text: 


Long 1 = (Long) p; // compile-time error #1 
EndPoint e = new EndPoint(); 
c = (Colorable)e; // compile-time error #2 


Here, the first compile-time error occurs because the class types Long and Point are 
unrelated (that is, they are not the same, and neither is a subclass of the other), so a cast 
between them will always fail. 


The second compile-time error occurs because a variable of type EndPoint can never 
reference a value that implements the interface Colorable. This is because EndPoint is 
a final type, and a variable of a final type always holds a value of the same run-time 
type as its compile-time type. Therefore, the run-time type of variable e must be exactly 
the type EndPoint, and type EndPoint does not implement Colorable. 
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Example 5.5-2. Casting for Array Types 


class Point { 
int x, y; 
Point (int x, int y) { this.x = x; this.y = y; } 
public String toString() { return "("+x+","+y+")"; } 
} 
interface Colorable { void setColor(int color); } 
class ColoredPoint extends Point implements Colorable { 
int color; 
ColoredPoint (int x, int y, int color) { 
super(x, y); setColor(color); 
} 
public void setColor(int color) { this.color = color; } 
public String toString() { 
return super.toString() + "@" + color; 


class Test { 

public static void main(String[] args) { 
Point[] pa = new ColoredPoint [4]; 
pa[0O] = new ColoredPoint (2, 2, 12); 
pa[l] = new ColoredPoint (4, 5, 24); 
ColoredPoint[] cpa = (ColoredPoint[])pa; 
System.out.print ("cpa: {"); 
for (int i = 0; i < cpa.length; i++) 

System.out.print((i == 0?" " : ", ") + cpalil); 

System.out.println(" }"); 


This program compiles without errors and produces the output: 


cpa: { (2,2)@12, (4,5)@24, null, null } 
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Example 5.5-3. Casting Incompatible Types at Run Time 
class Point { int x, y; } 
interface Colorable { void setColor(int color); } 
class ColoredPoint extends Point implements Colorable { 


int color; 
public void setColor(int color) { this.color = color; } 


class Test { 
public static void main(String[] args) { 

Point[] pa = new Point[100]; 
// The following line will throw a ClassCastException: 
ColoredPoint[] cpa = (ColoredPoint[])pa; 
System.out.println(cpa[0]); 
int[] shortvec = new int[2]; 
Object o = shortvec; 
// The following line will throw a ClassCastException: 


Colorable c = (Colorable)o; 
c.setColor(0); 


This program uses casts to compile, but it throws exceptions at run time, because the types 
are incompatible. 


5.6 Numeric Contexts 


Numeric contexts apply to the operands of an arithmetic operator. 

Numeric contexts allow the use of: 

* an identity conversion (§5.1.1) 

* a widening primitive conversion (§5.1.2) 

¢ a widening reference conversion (§5.1.5) followed by an unboxing conversion 


¢ a widening reference conversion followed by an unboxing conversion, then 
followed by a widening primitive conversion 


* an unboxing conversion (§5.1.8) 
¢ an unboxing conversion followed by a widening primitive conversion 


A numeric promotion is a process by which, given an arithmetic operator and its 
argument expressions, the arguments are converted to an inferred target type T. T 
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is chosen during promotion such that each argument expression can be converted 
to Tr and the arithmetic operation is defined for values of type T. 


The two kinds of numeric promotion are unary numeric promotion (§5.6.1) and 
binary numeric promotion (§5.6.2). 


5.6.1 Unary Numeric Promotion 


Some operators apply unary numeric promotion to a single operand, which must 
produce a value of a numeric type: 


¢ If the operand is of compile-time type Byte, Short, Character, Or Integer, it 
is subjected to unboxing conversion (§5.1.8). The result is then promoted to a 
value of type int by a widening primitive conversion (§5.1.2) or an identity 
conversion (§5.1.1). 


¢ Otherwise, if the operand is of compile-time type Long, Float, Or Double, it is 
subjected to unboxing conversion (§5.1.8). 


¢ Otherwise, if the operand is of compile-time type byte, short, or char, it is 
promoted to a value of type int by a widening primitive conversion (§5.1.2). 


¢ Otherwise, a unary numeric operand remains as is and is not converted. 
After the conversion(s), if any, value set conversion (§5.1.13) is then applied. 
Unary numeric promotion is performed on expressions in the following situations: 
¢ Each dimension expression in an array creation expression ($15.10.1) 
e The index expression in an array access expression (§15.10.3) 
¢ The operand of a unary plus operator + (§15.15.3) 
¢ The operand of a unary minus operator - (§15.15.4) 
¢ The operand of a bitwise complement operator ~ (§15.15.5) 
¢ Each operand, separately, of a shift operator <<, >>, or >>> (§15.19). 
A long shift distance (right operand) does not promote the value being shifted 
(left operand) to long. 
Example 5.6.1-1. Unary Numeric Promotion 


class Test { 
public static void main(String[] args) { 


byte b = 2; 
int a[] = new int[b]; // dimension expression promotion 
char c = '\u0001'; 
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a[c] = 1; // index expression promotion 
a[0] = -c; // unary - promotion 
System.out.printlin("a: " + a[0O] + "," + a[1]); 
b = -1; 
int i = ~b; // bitwise complement promotion 
System.out.println("~0Ox" + Integer.toHexString (b) 
+ "==0x" + Integer.toHexString(i)); 
= & << Bhy // shift promotion (left operand) 


System.out.printin("0Ox" + Integer.toHexString(b) 
+ "<<4L==0x" + Integer.toHexString(i)); 


} 
This program produces the output: 


a: -1,1 
~Oxffffrffff==0x0 
Oxffffffff<<4L=-Oxfffffffo 


5.6.2 Binary Numeric Promotion 


When an operator applies binary numeric promotion to a pair of operands, each 
of which must denote a value that is convertible to a numeric type, the following 
rules apply, in order: 


1. If any operand is of a reference type, it is subjected to unboxing conversion 
(§5.1.8). 


2. Widening primitive conversion (§5.1.2) is applied to convert either or both 
operands as specified by the following rules: 


¢ If either operand is of type double, the other is converted to double. 

¢ Otherwise, if either operand is of type float, the other is converted to float. 
¢ Otherwise, if either operand is of type long, the other is converted to long. 
¢ Otherwise, both operands are converted to type int. 


After the conversion(s), if any, value set conversion (§5.1.13) is then applied to 
each operand. 


Binary numeric promotion is performed on the operands of certain operators: 
¢ The multiplicative operators *, /, and 3 ($15.17) 

¢ The addition and subtraction operators for numeric types + and - (§15.18.2) 
e The numerical comparison operators <, <=, >, and >= (§15.20.1) 


¢ The numerical equality operators == and != (§15.21.1) 
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¢ The integer bitwise operators «, *, and | (§15.22.1) 


¢ In certain cases, the conditional operator ? : ($15.25) 


Example 5.6.2-1. Binary Numeric Promotion 


class Test { 
public static void main(String[] args) { 

int i = 0; 
float f = 1.0f; 
double d = 2.0; 
// First int*float is promoted to float*float, then 
// float==double is promoted to double==double: 
if (i * f == d) System.out.printin("oops") ; 


// A char&ébyte is promoted to intéint: 

byte b = Oxl1f; 

char c = 'G'; 

int control = c & b; 
System.out.printin(Integer.toHexString(control) ); 


// Here int:float is promoted to float:float: 


£ = (b==0) ? i: 4.0f; 
System.out.printin(1.0/f); 


This program produces the output: 


7 
0.25 


The example converts the ASCII character G to the ASCII control-G (BEL), by masking off 
all but the low 5 bits of the character. The 7 is the numeric value of this control character. 
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N AMES are used to refer to entities declared in a program. 


A declared entity ($6.1) is a package, class type (normal or enum), interface 
type (normal or annotation type), member (class, interface, field, or method) of 
a reference type, type parameter (of a class, interface, method or constructor), 
parameter (to a method, constructor, or exception handler), or local variable. 


Names in programs are either simple, consisting of a single identifier, or qualified, 
consisting of a sequence of identifiers separated by "." tokens ($6.2). 


Every declaration that introduces a name has a scope (§6.3), which is the part of the 
program text within which the declared entity can be referred to by a simple name. 


A qualified name nv. x may be used to refer to a member of a package or reference 
type, where n is a simple or qualified name and x is an identifier. If 1 names a 
package, then x is a member of that package, which is either a class or interface 
type or a subpackage. If v names a reference type or a variable of a reference type, 
then x names a member of that type, which is either a class, an interface, a field, 
or a method. 


In determining the meaning of a name (§6.5), the context of the occurrence is used 
to disambiguate among packages, types, variables, and methods with the same 
name. 


Access control (§6.6) can be specified in a class, interface, method, or field 
declaration to control when access to a member is allowed. Access is a different 
concept from scope. Access specifies the part of the program text within which the 
declared entity can be referred to by a qualified name. Access to a declared entity is 
also relevant in a field access expression (§15.11), a method invocation expression 
in which the method is not specified by a simple name (§ 15.12), a method reference 
expression ($15.13), or a qualified class instance creation expression (§15.9). In 
the absence of an access modifier, most declarations have package access, allowing 
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access anywhere within the package that contains its declaration; other possibilities 
are public, protected, and private. 


Fully qualified and canonical names (§6.7) are also discussed in this chapter. 


6.1 Declarations 


A declaration introduces an entity into a program and includes an identifier ($3.8) 
that can be used in a name to refer to this entity. The identifier is constrained to 
be a type identifier when the entity being introduced is a class, interface, or type 
parameter. 


A declared entity is one of the following: 
¢ A module, declared in a module declaration (§7.7) 
¢ A package, declared in a package declaration (§7.4) 


e An imported type, declared in a single-type-import declaration or a type-import- 
on-demand declaration (§7.5.1, §7.5.2) 


¢ An imported static member, declared in a single-static-import declaration or a 
static-import-on-demand declaration (§7.5.3, §7.5.4) 


¢ A class, declared in a class type declaration ($8.1) 
¢ An interface, declared in an interface type declaration ($9.1) 


¢ A type parameter, declared as part of the declaration of a generic class, interface, 
method, or constructor (§8.1.2, §9.1.2, §8.4.4, §8.8.4) 


¢ A member of a reference type (§8.2, §9.2, §8.9.3, §9.6, §10.7), one of the 
following: 


— A member class (§8.5, §9.5) 
— A member interface (§8.5, §9.5) 
— Anenum constant (§8.9) 
— A field, one of the following: 
>» A field declared in a class type or enum type (§8.3, §8.9.2) 
>» A field declared in an interface type or annotation type (§9.3, §9.6.1) 
>» The field length, which is implicitly a member of every array type ($10.7) 


— A method, one of the following: 
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>» A method (abstract or otherwise) declared in a class type or enum type 
($8.4, §8.9.2) 


>» A method (abstract or otherwise) declared in an interface type or 
annotation type (§9.4, §9.6.1) 


¢ A parameter, one of the following: 


— A formal parameter of a method or constructor of a class type or enum type 
(§8.4.1, $8.8.1, §8.9.2), or of a lambda expression (§15.27.1) 


— A formal parameter of an abst ract method of an interface type or annotation 
type (§9.4, §9.6.1) 


— An exception parameter of an exception handler declared in a catch clause of 
a try statement (§14.20) 


¢ A local variable, one of the following: 
— A local variable declared in a block (§14.4) 
— A local variable declared in a for statement (§14.14) 


Constructors (§8.8) are also introduced by declarations, but use the name of the 
class in which they are declared rather than introducing a new name. 


The declaration of a type which is not generic (class c ...) declares one 
entity: a non-generic type (c). A non-generic type is not a raw type, despite the 
syntactic similarity. In contrast, the declaration of a generic type (class C<T> ... 
or interface C<T> ...) declares two entities: a generic type (c<T>) and a 
corresponding non-generic type (c). In this case, the meaning of the term c depends 
on the context where it appears: 


¢ If genericity is unimportant, as in the non-generic contexts identified below, the 
identifier c denotes the non-generic type c. 


¢ If genericity is important, as in all contexts from §6.5 except the non-generic 
contexts, the identifier c denotes either: 


— The raw type c which is the erasure ($4.6) of the generic type c<T>; or 


— A parameterized type which is a particular parameterization (§4.5) of the 
generic type C<T>. 


The 14 non-generic contexts are as follows: 
1. Inauses or provides directive in a module declaration (§7.7.1) 


2. Ina single-type-import declaration ($7.5.1) 
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To the left of the . in a single-static-import declaration (§7.5.3) 

To the left of the . in a static-import-on-demand declaration (§7.5.4) 
To the left of the ( in a constructor declaration (§8.8) 

After the @ sign in an annotation (§9.7) 

To the left of .class ina class literal (§15.8.2) 


To the left of .this in a qualified this expression (§15.8.4) 


oS er ND HP & 


To the left of .super in a qualified superclass field access expression 
($15.11.2) 


10. To the left of .Jdentifier or . super . Identifier in a qualified method invocation 
expression ($15.12) 


11. To the left of . super: : in a method reference expression (§15.13) 


12. In a qualified expression name in a postfix expression or a try-with-resources 
statement (§15.14.1, §14.20.3) 


13. In a throws clause of a method or constructor (§8.4.6, §8.8.5, §9.4) 
14. In an exception parameter declaration (§14.20) 


The first eleven non-generic contexts correspond to the first eleven syntactic 
contexts for a TypeName in §6.5.1. The twelfth non-generic context is where 
a qualified ExpressionName such as c.x may include a TypeName c to denote 
static member access. The common use of TypeName in these twelve contexts 
is significant: it indicates that these contexts involve a less-than-first-class use 
of a type. In contrast, the thirteenth and fourteenth non-generic contexts employ 
ClassType, indicating that throws and catch clauses use types in a first-class way, 
in line with, say, field declarations. The characterization of these two contexts as 
non-generic is due to the fact that an exception type cannot be parameterized. 


Note that the ClassType production allows annotations, so it is possible to annotate the 
use of a type in a throws or catch clause, whereas the TypeName production disallows 
annotations, so it is not possible to annotate the name of a type in, say, a single-type-import 
declaration. 


Naming Conventions 


The class libraries of the Java SE Platform attempt to use, whenever possible, names chosen 
according to the conventions presented below. These conventions help to make code more 
readable and avoid certain kinds of name conflicts. 


We recommend these conventions for use in all programs written in the Java programming 
language. However, these conventions should not be followed slavishly if long-held 
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conventional usage dictates otherwise. So, for example, the sin and cos methods of 
the class java.lang.Math have mathematically conventional names, even though these 
method names flout the convention suggested here because they are short and are not verbs. 


Package Names and Module Names 


Developers should take steps to avoid the possibility of two published packages having the 
same name by choosing unique package names for packages that are widely distributed. 
This allows packages to be easily and automatically installed and catalogued. This 
section specifies a suggested convention for generating such unique package names. 
Implementations of the Java SE Platform are encouraged to provide automatic support for 
converting a set of packages from local and casual package names to the unique name 
format described here. 


If unique package names are not used, then package name conflicts may arise far from the 
point of creation of either of the conflicting packages. This may create a situation that is 
difficult or impossible for the user or programmer to resolve. The classes ClassLoader 
and ModuleLayer can be used to isolate packages with the same name from each other in 
those cases where the packages will have constrained interactions, but not in a way that is 
transparent to a naive program. 


You form a unique package name by first having (or belonging to an organization that has) 
an Internet domain name, such as oracle.com. You then reverse this name, component 
by component, to obtain, in this example, com.oracle, and use this as a prefix for 
your package names, using a convention developed within your organization to further 
administer package names. Such a convention might specify that certain package name 
components be division, department, project, machine, or login names. 


Example 6.1-1. Unique Package Names 


com.nighthacks.scrabble.dictionary 
org.openjdk.compiler.source.tree 
net.jcip.annotations 
edu.cmu.cs.bovik.cheese 
gov.whitehouse.socks.mousefinder 


The first component of a unique package name is always written in all-lowercase ASCII 
letters and should be one of the top level domain names, such as com, edu, gov, mil, net, 
or org, or one of the English two-letter codes identifying countries as specified in [SO 
Standard 3166. 


In some cases, the Internet domain name may not be a valid package name. Here are some 
suggested conventions for dealing with these situations: 


¢ Ifthe domain name contains a hyphen, or any other special character not allowed in an 
identifier (§3.8), convert it into an underscore. 


¢ If any of the resulting package name components are keywords (§3.9), append an 
underscore to them. 
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¢ Ifany of the resulting package name components start with a digit, or any other character 
that is not allowed as an initial character of an identifier, have an underscore prefixed 
to the component. 


The name of a module should correspond to the name of its principal exported package. If 
a module does not have such a package, or if for legacy reasons it must have a name that 
does not correspond to one of its exported packages, then its name should still start with 
the reversed form of an Internet domain with which its author is associated. 


Example 6.1-2. Unique Module Names 


com.nighthacks.scrabble 
org.openjdk.compiler 
net.jcip.annotations 


The first component of a package or module name must not be the identifier java. Package 
and module names that start with the identifier java are reserved for packages and modules 
of the Java SE Platform. 


The name of a package or module is not meant to imply where the package or module is 
stored on the Internet. For example, a package named edu. cmu.cs.bovik.cheese is not 
necessarily obtainable from the host cmu.edu or cs.cmu.edu or bovik.cs.cmu.edu. 
The suggested convention for generating unique package and module names is merely a 
way to piggyback a package and module naming convention on top of an existing, widely 
known unique name registry instead of having to create a separate registry for package and 
module names. 


Class and Interface Type Names 


Names of class types should be descriptive nouns or noun phrases, not overly long, in mixed 
case with the first letter of each word capitalized. 


Example 6.1-3. Descriptive Class Names 


ClassLoader 
SecurityManager 
Thread 

Dictionary 
BufferedInputStream 


Likewise, names of interface types should be short and descriptive, not overly long, in 
mixed case with the first letter of each word capitalized. The name may be a descriptive 
noun or noun phrase, which is appropriate when an interface is used as if it were an abstract 
superclass, such as interfaces java.io.DataInput and java.io.DataOutput; oritmay 
be an adjective describing a behavior, as for the interfaces Runnable and Cloneable. 


Type Variable Names 


Type variable names should be pithy (single character if possible) yet evocative, and should 
not include lower case letters. This makes it easy to distinguish type parameters from 
ordinary classes and interfaces. 
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Container types should use the name £ for their element type. Maps should use k for the 
type of their keys and v for the type of their values. The name x should be used for arbitrary 
exception types. We use T for type, whenever there is not anything more specific about the 
type to distinguish it. (This is often the case in generic methods.) 


If there are multiple type parameters that denote arbitrary types, one should use letters 
that neighbor T in the alphabet, such as s. Alternately, it is acceptable to use numeric 
subscripts (e.g., T1, T2) to distinguish among the different type variables. In such cases, all 
the variables with the same prefix should be subscripted. 


If a generic method appears inside a generic class, it is a good idea to avoid using the 
same names for the type parameters of the method and class, to avoid confusion. The same 
applies to nested generic classes. 


Example 6.1-4. Conventional Type Variable Names 


public class HashSet<E> extends AbstractSet<E> { ... } 
public class HashMap<K,V> extends AbstractMap<K,V> { ... } 
public class ThreadLocal<T> { ... } 
public interface Functor<T, X extends Throwable> { 

T eval() throws X; 


When type parameters do not fall conveniently into one of the categories mentioned, names 
should be chosen to be as meaningful as possible within the confines of a single letter. The 
names mentioned above (E, K, V, X, T) should not be used for type parameters that do not 
fall into the designated categories. 


Method Names 


Method names should be verbs or verb phrases, in mixed case, with the first letter lowercase 
and the first letter of any subsequent words capitalized. Here are some additional specific 
conventions for method names: 


* Methods to get and set an attribute that might be thought of as a variable V should be 
named get Vand set v. An example is the methods get Priority and setPriority 
of class Thread. 


¢ A method that returns the length of something should be named length, as in class 
String. 


e A method that tests a boolean condition V about an object should be named isv. An 
example is the method isInterrupted of class Thread. 


¢ A method that converts its object to a particular format F should be named 
tor. Examples are the method toString of class Object and the methods 
toLocaleString and toGMTString of class java.util.Date. 


Whenever possible and appropriate, basing the names of methods in a new class on names 
in an existing class that is similar, especially a class from the Java SE Platform API, will 
make it easier to use. 
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Field Names 


Names of fields that are not final should be in mixed case with a lowercase first letter 
and the first letters of subsequent words capitalized. Note that well-designed classes have 
very few public or protected fields, except for fields that are constants (static final 
fields). 


Fields should have names that are nouns, noun phrases, or abbreviations for nouns. 


Examples of this convention are the fields buf, pos, and count of the class 
java.io.ByteArrayInputStream and the field bytesTransferred of the class 
java.io.InterruptedIOException 


Constant Names 


The names of constants in interface types should be, and final variables of class types 
may conventionally be, a sequence of one or more words, acronyms, or abbreviations, 
all uppercase, with components separated by underscore "_" characters. Constant names 
should be descriptive and not unnecessarily abbreviated. Conventionally they may be any 
appropriate part of speech. 


Examples of names for constants include MIN_VALUE, MAX_VALUE, MIN_RADIXx, and 
MAX_RADIX of the class Character. 


A group of constants that represent alternative values of a set, or, less frequently, masking 
bits in an integer value, are sometimes usefully specified with a common acronym as a 
name prefix. 


For example: 


interface ProcessStates { 
int PS_RUNNING 0; 
int PS_SUSPENDED “Ls 


Local Variable and Parameter Names 


Local variable and parameter names should be short, yet meaningful. They are often short 
sequences of lowercase letters that are not words, such as: 


¢ Acronyms, that is the first letter of a series of words, as in cp for a variable holding a 
reference to a ColoredPoint 
e Abbreviations, as in buf holding a pointer to a buffer of some kind 


¢ Mnemonic terms, organized in some way to aid memory and understanding, typically 
by using a set of local variables with conventional names patterned after the names of 
parameters to widely used classes. For example: 


— in and out, whenever some kind of input and output are involved, patterned 
after the fields of System 
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— off and len, whenever an offset and length are involved, patterned after the 
parameters to the read and write methods of the interfaces DataInput and 
DataOutput of java.io 


One-character local variable or parameter names should be avoided, except for temporary 
and looping variables, or where a variable holds an undistinguished value of a type. 
Conventional one-character names are: 

* bforabyte 

* cforachar 

¢ dfora double 

¢ efor an Exception 

¢ f£ fora float 

¢ i, j, and k for ints 

* 1 fora long 

* o for an Object 

* s fora String 

¢ v for an arbitrary value of some type 

Local variable or parameter names that consist of only two or three lowercase letters should 


not conflict with the initial country codes and domain names that are the first component 
of unique package names. 


6.2 Names and Identifiers 


A name is used to refer to an entity declared in a program. 
There are two forms of names: simple names and qualified names. 
A simple name is a single identifier. 


wom 


A qualified name consists of a name, a"." token, and an identifier. 


In determining the meaning of a name (§6.5), the context in which the name appears 
is taken into account. The rules of §6.5 distinguish among contexts where a name 
must denote (refer to) a package (§6.5.3), a type (§6.5.5), a variable or value in an 


expression (§6.5.6), or a method (§6.5.7). 


Packages and reference types have members which may be accessed by qualified names. 
As background for the discussion of qualified names and the determination of the meaning 
of names, see the descriptions of membership in §4.4, §4.5.2, §4.8, §4.9, §7.1, §8.2, §9.2, 
and §10.7. 
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Not all identifiers in a program are a part of a name. Identifiers are also used in 
the following situations: 


In declarations ($6.1), where an identifier may occur to specify the name by 
which the declared entity will be known. 


As labels in labeled statements ($14.7) and in break and continue statements 
($14.15, §14.16) that refer to statement labels. 


The identifiers used in labeled statements and their associated break and 
continue statements are completely separate from those used in declarations. 


wom 


In field access expressions ($15.11), where an identifier occurs after a" ." token 


wow 


to indicate a member of the object denoted by the expression before the "." token, 


wom 


or the object denoted by the super or TypeName. super before the "." token. 


In some method invocation expressions ($15.12), wherever an identifier occurs 


wom 


after a '"." token and before a "(" token to indicate a method to be invoked for 


wom 


the object denoted by the expression before the "." token, or the type denoted 


wom 


by the TypeName before the "." token, or the object denoted by the super or 


wom 


TypeName. super before the "." token. 


In some method reference expressions (§15.13), wherever an identifier occurs 
after a": :" token to indicate a method of the object denoted by the expression 
before the "::" token, or the type denoted by the TypeName before the ": :" 
token, or the object denoted by the super or TypeName .super before the ": :" 
token. 


In qualified class instance creation expressions ($15.9), where an identifier 
occurs to the right of the new token to indicate a type that is a member of the 
compile-time type of the expression preceding the new token. 


In element-value pairs of annotations (§9.7.1), to denote an element of the 
corresponding annotation type. 


In this program: 


class Test { 
public static void main(String[] args) { 
Class c = System.out.getClass(); 
System.out.printin(c.toString().length() + 
args[0].length() + args.length) ; 


} 


the identifiers Test, main, and the first occurrences of args and c are not names. Rather, 
they are identifiers used in declarations to specify the names of the declared entities. The 
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names String, Class, System.out.getClass, System.out.printiln, c.toString, 
args, and args. length appear in the example. 


The occurrence of lengthin args. lengthis a name because args. length is a qualified 
name (§6.5.6.2) and not a field access expression ($15.11). A field access expression, as 
well as a method invocation expression, a method reference expression, and a qualified class 
instance creation expression, uses an identifier rather than a name to denote the member of 
interest. Thus, the occurrence of length in args[0].length() is nota name, but rather 
an identifier appearing in a method invocation expression. 


One might wonder why these kinds of expression use an identifier rather than a simple 
name, which is after all just an identifier. The reason is that a simple expression name is 
defined in terms of the lexical environment; that is, a simple expression name must be in the 
scope of a variable declaration (§6.5.6.1). On the other hand, field access, qualified method 
invocation, method references, and qualified class instance creation all refer to members 
whose names are not in the lexical environment. By definition, such names are bound only 
in the context provided by the Primary of the field access expression, method invocation 
expression, method reference expression, or class instance creation expression; or by the 
super of the field access expression, method invocation expression, or method reference 
expression; and so on. Thus, we denote such members with identifiers rather than simple 
names. 


To complicate things further, a field access expression is not the only way to denote a 
field of an object. For parsing reasons, a qualified name is used to denote a field of an in- 
scope variable. (The variable itself is denoted with a simple name, alluded to above.) It is 
necessary for access control (§6.6) to apply to both denotations of a field. 


6.3 Scope of a Declaration 


The scope of a declaration is the region of the program within which the entity 
declared by the declaration can be referred to using a simple name, provided it is 
not shadowed (86.4.1). 


A declaration is said to be in scope at a particular point in a program if and only 
if the declaration's scope includes that point. 


The scope of the declaration of an observable top level package (§7.4.3) is all 
observable compilation units associated with modules to which the package is 
uniquely visible (§7.4.3). 


The declaration of a package that is not observable is never in scope. 
The declaration of a subpackage is never in scope. 
The package java is always in scope. 


The scope of a type imported by a single-type-import declaration (§7.5.1) or a type- 
import-on-demand declaration (§7.5.2) is the module declaration ($7.7) and all the 
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class and interface type declarations ($7.6) of the compilation unit in which the 
import declaration appears, as well as any annotations on the module declaration 
or package declaration of the compilation unit. 


The scope of a member imported by a single-static-import declaration (§7.5.3) 
or a static-import-on-demand declaration (§7.5.4) is the module declaration and 
all the class and interface type declarations of the compilation unit in which the 
import declaration appears, as well as any annotations on the module declaration 
or package declaration of the compilation unit. 


The scope of a top level type (§7.6) is all type declarations in the package in which 
the top level type is declared. 


The scope of a declaration of a member m declared in or inherited by a class type c 
($8.1.6) is the entire body of c, including any nested type declarations. 


The scope of a declaration of a member m declared in or inherited by an interface 
type r ($9.1.4) is the entire body of r, including any nested type declarations. 


The scope of an enum constant c declared in an enum type r is the body of 7, and 
any case label of a switch statement whose expression is of enum type 7(§14.11). 


The scope of a formal parameter of a method (§8.4.1), constructor (§8.8.1), or 
lambda expression ($15.27) is the entire body of the method, constructor, or lambda 
expression. 


The scope of a class's type parameter (§8.1.2) is the type parameter section of the 
class declaration, the type parameter section of any superclass or superinterface of 
the class declaration, and the class body. 


The scope of an interface's type parameter (§9.1.2) is the type parameter section 
of the interface declaration, the type parameter section of any superinterface of the 
interface declaration, and the interface body. 


The scope of a method's type parameter (§8.4.4) is the entire declaration of the 
method, including the type parameter section, but excluding the method modifiers. 


The scope of a constructor's type parameter (§8.8.4) is the entire declaration of 
the constructor, including the type parameter section, but excluding the constructor 
modifiers. 


The scope of a local class declaration immediately enclosed by a block ($14.2) is 
the rest of the immediately enclosing block, including its own class declaration. 


The scope of a local class declaration immediately enclosed by a switch block 
statement group (§14.11) is the rest of the immediately enclosing switch block 
statement group, including its own class declaration. 
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The scope of a local variable declaration in a block (§14.4) is the rest of the block 
in which the declaration appears, starting with its own initializer and including any 
further declarators to the right in the local variable declaration statement. 


The scope of a local variable declared in the For/nit part of a basic for statement 
(§14.14.1) includes all of the following: 


¢ Its own initializer 

e Any further declarators to the right in the For/nit part of the for statement 
¢ The Expression and ForUpdate parts of the for statement 

¢ The contained Statement 


The scope of a local variable declared in the FormalParameter part of an enhanced 
for statement (§14.14.2) is the contained Statement. 


The scope of a parameter of an exception handler that is declared in a catch clause 
of a try statement (§14.20) is the entire block associated with the catch. 


The scope of a variable declared in the ResourceSpecification of a try-with- 
resources statement (§ 14.20.3) is from the declaration rightward over the remainder 
of the ResourceSpecification and the entire t ry block associated with the t ry-with- 
resources statement. 


The translation of a t ry-with-resources statement implies the rule above. 
Example 6.3-1. Scope of Type Declarations 


These rules imply that declarations of class and interface types need not appear before uses 
of the types. In the following program, the use of PointList in class Point is valid, 
because the scope of the class declaration Point List includes both class Point and class 
PointList, as well as any other type declarations in other compilation units of package 
points. 


package points; 
class Point { 
int x, y; 
PointList list; 
Point next; 


} 


class PointList { 
Point first; 


} 
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Example 6.3-2. Scope of Local Variable Declarations 


The following program causes a compile-time error because the initialization of local 
variable x is within the scope of the declaration of local variable x, but the local variable 
x does not yet have a value and cannot be used. The field x has a value of 0 (assigned 
when Test1 was initialized) but is a red herring since it is shadowed (86.4.1) by the local 
variable x. 


class Testl { 
static int x; 
public static void main(String[] args) { 
int x = x; 


The following program does compile: 


class Test2 { 
static int x; 
public static void main(String[] args) { 
int x = (x=2)*2; 


System.out.printin (x); 


because the local variable x is definitely assigned (§16 (Definite Assignment)) before it is 
used. It prints: 


In the following program, the initializer for three can correctly refer to the variable two 
declared in an earlier declarator, and the method invocation in the next line can correctly 
refer to the variable three declared earlier in the block. 


class Test3 { 
public static void main(String[] args) { 
System.out.print ("2+1="); 


int two = 2, three = two + 1; 
System.out.println (three) ; 


This program produces the output: 


2+1=3 
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6.4 Shadowing and Obscuring 


A local variable (§14.4), formal parameter (§8.4.1, §15.27.1), exception parameter 
($14.20), and local class ($14.3) can only be referred to using a simple name, not 
a qualified name (§6.2). 


Some declarations are not permitted within the scope of a local variable, formal 
parameter, exception parameter, or local class declaration because it would be 
impossible to distinguish between the declared entities using only simple names. 


For example, if the name of a formal parameter of a method could be redeclared as the name 
of a local variable in the method body, then the local variable would shadow the formal 
parameter and there would be no way to refer to the formal parameter - an undesirable 
outcome. 


It is a compile-time error if the name of a formal parameter is used to declare a new 
variable within the body of the method, constructor, or lambda expression, unless 
the new variable is declared within a class declaration contained by the method, 
constructor, or lambda expression. 


It is a compile-time error if the name of a local variable v is used to declare a new 
variable within the scope of v, unless the new variable is declared within a class 
whose declaration is within the scope of v. 


It is a compile-time error if the name of an exception parameter is used to declare 
a new variable within the Block of the catch clause, unless the new variable is 
declared within a class declaration contained by the Block of the catch clause. 


It is acompile-time error if the name of a local class cis used to declare a new local 
class within the scope of c, unless the new local class is declared within another 
class whose declaration is within the scope of c. 


These rules allow redeclaration of a variable or local class in nested class declarations that 
occur in the scope of the variable or local class; such nested class declarations may be local 
classes (§ 14.3) or anonymous classes ($15.9). Thus, the declaration of a formal parameter, 
local variable, or local class may be shadowed in a class declaration nested within a method, 
constructor, or lambda expression; and the declaration of an exception parameter may be 
shadowed in a class declaration nested within the Block of the catch clause. 


There are two design alternatives for handling name clashes created by lambda parameters 
and other variables declared in lambda expressions. One is to mimic class declarations: like 
local classes, lambda expressions introduce a new "level" for names, and all variable names 
outside the expression can be redeclared. Another is a "local" strategy: like cat ch clauses, 
for loops, and blocks, lambda expressions operate at the same "level" as the enclosing 
context, and local variables outside the expression cannot be shadowed. The above rules 
use the local strategy; there is no special dispensation that allows a variable declared in a 
lambda expression to shadow a variable declared in an enclosing method. 


6.4 
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Note that the rule for local classes does not make an exception for a class of the same name 
declared within the local class itself. However, this case is prohibited by a separate rule: a 
class cannot have the same name as a class that encloses it (§8.1). 


Example 6.4-1. Attempted Shadowing Of A Local Variable 


Because a declaration of an identifier as a local variable of a method, constructor, or 
initializer block must not appear within the scope of a parameter or local variable of the 
same name, a compile-time error occurs for the following program: 


class Testl { 
public static void main(String[] args) { 
int i; 
for (int i = 0; i < 10; i++) 
System.out.printin(i); 


This restriction helps to detect some otherwise very obscure bugs. A similar restriction on 
shadowing of members by local variables was judged impractical, because the addition of 
a member in a superclass could cause subclasses to have to rename local variables. Related 
considerations make restrictions on shadowing of local variables by members of nested 
classes, or on shadowing of local variables by local variables declared within nested classes 
unattractive as well. 


Hence, the following program compiles without error: 


class Test2 { 
public static void main(String[] args) { 
int. Tt; 
class Local { 
{ 
for (int i = 0; i < 10; i++) 
System.out.printin(i); 


} 


new Local (); 


On the other hand, local variables with the same name may be declared in two separate 
blocks or for statements, neither of which contains the other: 


class Test3 { 
public static void main(String[] args) { 


for (int i = 0; i < 10; i++) 
System.out.print(i + " "); 

for (int i = 10; i> 0; i--) 
System.out.print(i + " "); 


System.out.println(); 
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} 
This program compiles without error and, when executed, produces the output: 


012345678910987654321 


6.4.1 Shadowing 


Some declarations may be shadowed in part of their scope by another declaration of 
the same name, in which case a simple name cannot be used to refer to the declared 
entity. 


Shadowing is distinct from hiding (§8.3, §8.4.8.2, §8.5, §9.3, 89.5), which applies 
only to members which would otherwise be inherited but are not because of a 
declaration in a subclass. Shadowing is also distinct from obscuring (§6.4.2). 


A declaration a of a type named n shadows the declarations of any other types 
named n that are in scope at the point where da occurs throughout the scope of d. 


A declaration a of a field or formal parameter named n shadows, throughout the 
scope of a, the declarations of any other variables named n that are in scope at the 
point where d occurs. 


A declaration d of a local variable or exception parameter named n shadows, 
throughout the scope of a, (a) the declarations of any other fields named n that are 
in scope at the point where doccurs, and (b) the declarations of any other variables 
named n that are in scope at the point where d occurs but are not declared in the 
innermost class in which dis declared. 


A declaration dof a method named n shadows the declarations of any other methods 
named n that are in an enclosing scope at the point where a occurs throughout the 
scope of a. 


A package declaration never shadows any other declaration. 


A type-import-on-demand declaration never causes any other declaration to be 
shadowed. 


A static-import-on-demand declaration never causes any other declaration to be 
shadowed. 


A single-type-import declaration din a compilation unit c of package p that imports 
a type named n shadows, throughout c, the declarations of: 


¢ any top level type named n declared in another compilation unit of p 


* any type named n imported by a type-import-on-demand declaration in c 
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* any type named n imported by a static-import-on-demand declaration in c 


A single-static-import declaration d in a compilation unit c of package p that 
imports a field named n shadows the declaration of any static field named n 
imported by a static-import-on-demand declaration in c, throughout c. 


A single-static-import declaration d in a compilation unit c of package p that 
imports a method named n with signature s shadows the declaration of any 
static method named n with signature s imported by a static-import-on-demand 
declaration in c, throughout c. 


A single-static-import declaration d in a compilation unit c of package p that 
imports a type named n shadows, throughout c, the declarations of: 


* any static type named n imported by a static-import-on-demand declaration in c; 


¢ any top level type ($7.6) named n declared in another compilation unit (§7.3) 
of p; 


* any type named n imported by a type-import-on-demand declaration (§7.5.2) in 
Cc. 


Example 6.4.1-1. Shadowing of a Field Declaration by a Local Variable Declaration 


class Test { 
static int x = 1; 
public static void main(String[] args) { 
int x = 0; 
System.out.print ("x="_ + x); 
System.out.println(", Test.x=" + Test.x); 


} 

This program produces the output: 
x=0, Test.x=1 

This program declares: 


* aclass Test 

* aclass (static) variable x that is a member of the class Test 
¢ aclass method main that is a member of the class Test 

* a parameter args of the main method 

¢ alocal variable x of the main method 


Since the scope of a class variable includes the entire body of the class (§8.2), the class 
variable x would normally be available throughout the entire body of the method main. 
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In this example, however, the class variable x is shadowed within the body of the method 
main by the declaration of the local variable x. 


A local variable has as its scope the rest of the block in which it is declared (§6.3); in 
this case this is the rest of the body of the main method, namely its initializer "0" and the 
invocations of System.out.print and System.out.printin 


This means that: 


¢ The expression x in the invocation of print refers to (denotes) the value of the local 
variable x. 


¢ The invocation of print1n uses a qualified name ($6.6) Test .x, which uses the class 
type name Test to access the class variable x, because the declaration of Test .x is 
shadowed at this point and cannot be referred to by its simple name. 


The keyword this can also be used to access a shadowed field x, using the form this. x. 
Indeed, this idiom typically appears in constructors (§8.8): 


class Pair { 
Object first, second; 
public Pair(Object first, Object second) { 
this.first = first; 
this.second = second; 


Here, the constructor takes parameters having the same names as the fields to be initialized. 
This is simpler than having to invent different names for the parameters and is not too 
confusing in this stylized context. In general, however, it is considered poor style to have 
local variables with the same names as fields. 


Example 6.4.1-2. Shadowing of a Type Declaration by Another Type Declaration 


import java.util.*; 
class Vector { 
int val[] ={1, 2 }; 


class Test { 
public static void main(String[] args) { 
Vector v = new Vector(); 
System.out.printin(v.val[0]); 


The program compiles and prints: 
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using the class Vector declared here in preference to the generic class 
java.util.Vector (§8.1.2) that might be imported on demand. 


6.4.2 Obscuring 


A simple name may occur in contexts where it may potentially be interpreted as 
the name of a variable, a type, or a package. In these situations, the rules of §6.5.2 
specify that a variable will be chosen in preference to a type, and that a type will be 
chosen in preference to a package. Thus, it is may sometimes be impossible to refer 
to a type or package via its simple name, even though its declaration is in scope 
and not shadowed. We say that such a declaration is obscured. 


Obscuring is distinct from shadowing (§6.4.1) and hiding (§8.3, §8.4.8.2, §8.5, 
§9.3, §9.5). 


There is no obscuring between the name of a module and the name of a variable, 
type, or package; thus, modules may share names with variables, types, and 
packages, though it is not necessarily recommended to name a module after a 
package it contains. 


The naming conventions of §6.1 help reduce obscuring, but if it does occur, here are some 
notes about what you can do to avoid it. 


When package names occur in expressions: 

¢ Ifa package name is obscured by a field declaration, then import declarations (§7.5) 
can usually be used to make available the type names declared in that package. 

¢ Ifapackage name is obscured by a declaration of a parameter or local variable, then the 


name of the parameter or local variable can be changed without affecting other code. 


The first component of a package name is normally not easily mistaken for a type name, as a 
type name normally begins with a single uppercase letter. (The Java programming language 
does not actually rely on case distinctions to determine whether a name is a package name 
or a type name.) 


Obscuring involving class and interface type names is rare. Names of fields, parameters, 
and local variables normally do not obscure type names because they conventionally begin 
with a lowercase letter whereas type names conventionally begin with an uppercase letter. 


Method names cannot obscure or be obscured by other names (§6.5.7). 
Obscuring involving field names is rare; however: 


¢ Ifa field name obscures a package name, then an import declaration (§7.5) can usually 
be used to make available the type names declared in that package. 
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¢ Ifa field name obscures a type name, then a fully qualified name for the type can be used 
unless the type name denotes a local class (§14.3). 


¢ Field names cannot obscure method names. 


¢ Ifa field name is shadowed by a declaration of a parameter or local variable, then the 
name of the parameter or local variable can be changed without affecting other code. 


Obscuring involving constant names is rare: 


¢ Constant names normally have no lowercase letters, so they will not normally obscure 
names of packages or types, nor will they normally shadow fields, whose names typically 
contain at least one lowercase letter. 


¢ Constant names cannot obscure method names, because they are distinguished 
syntactically. 


6.5 Determining the Meaning of a Name 


The meaning of a name depends on the context in which it is used. The 
determination of the meaning of a name requires three steps: 


¢ First, context causes a name syntactically to fall into one of seven categories: 
ModuleName, PackageName, TypeName, ExpressionName, MethodName, 
PackageOrTypeName, or AmbiguousName. 


TypeName is less expressive than the other six categories, because it is denoted 
with Typeldentifier, which excludes the character sequence var (§3.8). 


¢ Second, aname that is initially classified by its context as an AmbiguousName or 
as a PackageOrTypeName is then reclassified to be a PackageName, TypeName, 
or ExpressionName. 


¢ Third, the resulting category then dictates the final determination of the meaning 
of the name (or a compile-time error if the name has no meaning). 


ModuleName: 
Identifier 
ModuleName . Identifier 


PackageName: 
Identifier 
PackageName . Identifier 
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6.5.1 Syntactic Classification of a Name According to Context 


A name is syntactically classified as a ModuleName in these contexts: 


¢ Ina requires directive in a module declaration (§7.7.1) 


TypeName: 
Typeldentifier 
PackageOrTypeName . Typeldentifier 


PackageOrTypeName: 
Identifier 
PackageOrTypeName . Identifier 


ExpressionName: 
Identifier 
AmbiguousName . Identifier 


MethodName: 
Identifier 


AmbiguousName: 
Identifier 
AmbiguousName . Identifier 


NAMES 


The use of context helps to minimize name conflicts between entities of different 
kinds. Such conflicts will be rare if the naming conventions described in §6.1 are 
followed. Nevertheless, conflicts may arise unintentionally as types developed by different 
programmers or different organizations evolve. For example, types, methods, and fields 
may have the same name. It is always possible to distinguish between a method and a field 
with the same name, since the context of a use always tells whether a method is intended. 


¢ To the right of to in an exports or opens directive in a module declaration 
(§7.7.2) 


A name is syntactically classified as a PackageName in these contexts: 
¢ To the right of exports or opens in a module declaration 

¢ To the left of the "." in a qualified PackageName 

A name is syntactically classified as a TypeName in these contexts: 

¢ The first eleven non-generic contexts (§6.1): 


1. 


In a uses or provides directive in a module declaration (§7.7.1) 
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10. 


11. 


In a single-type-import declaration (§7.5.1) 

To the left of the . in a single-static-import declaration (§7.5.3) 

To the left of the . in a static-import-on-demand declaration (§7.5.4) 
To the left of the ( in a constructor declaration (§8.8) 

After the @ sign in an annotation (§9.7) 

To the left of .class in a class literal (§15.8.2) 

To the left of .this in a qualified this expression (§$15.8.4) 


To the left of .super in a qualified superclass field access expression 
($15.11.2) 


To the left of .Jdentifier or .super.Identifier in a qualified method 
invocation expression (§15.12) 


To the left of .super:: in a method reference expression ($15.13) 


¢ As the /dentifier or dotted Identifier sequence that constitutes any ReferenceType 
(including a ReferenceType to the left of the brackets in an array type, or to 
the left of the < in a parameterized type, or in a non-wildcard type argument 
of a parameterized type, or in an extends or super Clause of a wildcard type 
argument of a parameterized type) in the 16 contexts where types are used 


($4.11): 


1. 


In an extends Or implements clause of a class declaration (§8.1.4, §8.1.5, 
§8.5, §9.5) 


In an extends clause of an interface declaration (§9.1.3) 


The return type of a method (§8.4, §9.4) (including the type of an element 
of an annotation type (§9.6.1)) 


In the throws clause of a method or constructor (§8.4.6, §8.8.5, §9.4) 


In an extends clause of a type parameter declaration of a generic class, 
interface, method, or constructor (§8.1.2, §9.1.2, §8.4.4, §8.8.4) 


The type in a field declaration of a class or interface ($8.3, $9.3) 


The type in a formal parameter declaration of a method, constructor, or 
lambda expression (§8.4.1, §8.8.1, §9.4, §15.27.1) 


The type of the receiver parameter of a method (§8.4) 
The type in a local variable declaration (§ 14.4, §14.14.1, §14.14.2, §14.20.3) 
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10. A type in an exception parameter declaration (§ 14.20) 
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11. In an explicit type argument list to an explicit constructor invocation 
statement or class instance creation expression or method invocation 


expression (§8.8.7.1, §15.9, §15.12) 


12. In an unqualified class instance creation expression, either as the class type 
to be instantiated ($15.9) or as the direct superclass or direct superinterface 


of an anonymous class to be instantiated (§15.9.5) 
13. The element type in an array creation expression (§15.10.1) 
14. The type in the cast operator of a cast expression ($15.16) 
15. The type that follows the instanceof relational operator (§15.20.2) 


16. In a method reference expression (§15.13), as the reference type to search 


for a member method or as the class type or array type to construct. 


The extraction of a TypeName from the identifiers of a ReferenceType in the 16 contexts 
above is intended to apply recursively to all sub-terms of the ReferenceType, such as its 
element type and any type arguments. 


For example, suppose a field declaration uses the type p.q.Foo[]. The brackets of the 
array type are ignored, and the term p. q. Foo is extracted as a dotted sequence of Identifiers 
to the left of the brackets in an array type, and classified as a TypeName. A later step 
determines which of p, gq, and Foo is a type name or a package name. 


As another example, suppose a cast operator uses the type p.q. Foo<? extends String>. 
The term p.q.Foo is again extracted as a dotted sequence of Identifier terms, this time 
to the left of the < in a parameterized type, and classified as a TypeName. The term 
String is extracted as an /dentifier in an extends clause of a wildcard type argument of 
a parameterized type, and classified as a TypeName. 


A name is syntactically classified as an ExpressionName in these contexts: 


¢ As the qualifying expression in a qualified superclass constructor invocation 


(§8.8.7.1) 


¢ As the qualifying expression in a qualified class instance creation expression 


($15.9) 


¢ As the array reference expression in an array access expression (§15.10.3) 


¢ As a PostfixExpression (§15.14) 


As the left-hand operand of an assignment operator ($15.26) 


¢ Asa VariableAccess in a try-with-resources statement (§14.20.3) 
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A name is syntactically classified as a MethodName in this context: 

¢ Before the "(" in a method invocation expression ($15.12) 

A name is syntactically classified as a PackageOrTypeName in these contexts: 
¢ To the left of the "." in a qualified TypeName 

¢ In a type-import-on-demand declaration ($7.5.2) 

A name is syntactically classified as an AmbiguousName in these contexts: 

¢ To the left of the "." in a qualified ExpressionName 


¢ To the left of the rightmost . that occurs before the "(" in a method invocation 
expression 


¢ To the left of the "." in a qualified AmbiguousName 


¢ In the default value clause of an annotation type element declaration (§9.6.2) 


¢ To the right of an "=" in an an element-value pair (§9.7.1) 


¢ To the left of : : in a method reference expression ($15.13) 


The effect of syntactic classification is to restrict certain kinds of entities to certain parts 
of expressions: 


¢ The name ofa field, parameter, or local variable may be used as an expression (§15.14.1). 


¢ The name of a method may appear in an expression only as part of a method invocation 
expression (§15.12). 


¢ The name of a class or interface type may appear in an expression only as part of a 
class literal (§15.8.2), a qualified this expression (§15.8.4), a class instance creation 
expression (§15.9), an array creation expression (§15.10.1), a cast expression (§15.16), 
an instanceof expression (§15.20.2), an enum constant (§8.9), or as part of a qualified 
name for a field or method. 


¢ The name of a package may appear in an expression only as part of a qualified name 
for a class or interface type. 


6.5.2 Reclassification of Contextually Ambiguous Names 
An AmbiguousName is then reclassified as follows. 
If the AmbiguousName is a simple name, consisting of a single /dentifier: 


¢ If the Identifier appears within the scope (§6.3) of a local variable declaration 
(§14.4) or parameter declaration (§8.4.1, §8.8.1, $14.20) or field declaration 
(§8.3) with that name, then the AmbiguousName is reclassified as an 
ExpressionName. 
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Otherwise, if a field of that name is declared in the compilation unit (§7.3) 
containing the Identifier by a single-static-import declaration (§7.5.3), or by 
a static-import-on-demand declaration (§7.5.4) then the AmbiguousName is 
reclassified as an ExpressionName. 


Otherwise, if the Identifier is a valid Typeldentifier and appears within the 
scope (§6.3) of a top level class (§8 (Classes)) or interface type declaration (§9 
(Unterfaces)), a local class declaration (§14.3) or member type declaration (§8.5, 
§9.5) with that name, then the AmbiguousName is reclassified as a TypeName. 


Otherwise, if the Identifier is a valid Typeldentifier and a type of that name 
is declared in the compilation unit ($7.3) containing the Identifier, either 
by a single-type-import declaration (§7.5.1), or by a type-import-on-demand 
declaration (§7.5.2), or by a single-static-import declaration (§7.5.3), or by 
a static-import-on-demand declaration (§7.5.4), then the AmbiguousName is 
reclassified as a TypeName. 


Otherwise, the AmbiguousName is reclassified as a PackageName. A later step 
determines whether or not a package of that name actually exists. 


wow 


If the AmbiguousName is a qualified name, consisting of a name, a '".", and an 
Identifier, then the name to the left of the "." is first reclassified, for it is itself an 
AmbiguousName. There is then a choice: 


¢ If the name to the left of the "." is reclassified as a PackageName, then: 


— If the Identifier is a valid Typeldentifier, and there is a package whose name 
is the name to the left of the ".", and that package contains a declaration of 
a type whose name is the same as the /dentifier, then this AmbiguousName is 


reclassified as a TypeName. 


— Otherwise, this AmbiguousName is reclassified as a PackageName. A later 
step determines whether or not a package of that name actually exists. 


¢ If the name to the left of the "." is reclassified as a TypeName, then: 


— If the Identifier is the name of a method or field of the type denoted by 
TypeName, then this AmbiguousName is reclassified as an ExpressionName. 


— Otherwise, if the /dentifier is a valid Typeldentifier and is the name of a 
member type of the type denoted by TypeName, then this AmbiguousName is 
reclassified as a TypeName. 


— Otherwise, a compile-time error occurs. 
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¢ If the name to the left of the "." is reclassified as an ExpressionName, then this 
AmbiguousName is reclassified as an ExpressionName. A later step determines 
whether or not a member with the name /dentifier actually exists. 


The requirement that a potential type name be "a valid Typeldentifier" prevents treating var 
as a type name. It is usually redundant, because the rules for declarations already prevent 
the introduction of types named var. However, in some cases, a compiler may find a binary 
class named var, and we want to be clear that such classes can never be named. The simplest 
solution is to consistently check for a valid Typeldentifier. 


Example 6.5.2-1. Reclassification of Contextually Ambiguous Names 


Consider the following contrived "library code": 


package org.rpgpoet; 
import java.util.Random; 
public interface Music { Random[] wizards = new Random[4]; } 


and then consider this example code in another package: 


package bazola; 
class Gabriel { 
static int n = org.rpgpoet.Music.wizards.length; 


First of all, the name org.rpgpoet .Music.wizards.length is classified as an 
ExpressionName because it functions as a PostfixExpression. Therefore, each of the names: 


org.rpgpoet .Music.wizards 
org.rpgpoet .Music 
org.rpgpoet 

org 


is initially classified as an AmbiguousName. These are then reclassified: 
¢ The simple name org is reclassified as a PackageName (since there is no variable or 


type named org in scope). 


¢ Next, assuming that there is no class or interface named rpgpoet in any compilation unit 
of package org (and we know that there is no such class or interface because package org 
has a subpackage named rpgpoet), the qualified name org. rpgpoet is reclassified as 
a PackageName. 


e Next, because package org.rpgpoet has an accessible ($6.6) interface type named 
Music, the qualified name org. rpgpoet .Music Is reclassified as a TypeName. 


¢ Finally, because the name org.rpgpoet .Music is a TypeName, the qualified name 
org.rpgpoet .Music.wizards is reclassified as an ExpressionName. 
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6.5.3 Meaning of Module Names and Package Names 


The module name M, whether simple or qualified, denotes the module (if any) with 
that name. 


This section does not mandate a compile-time error if no module with that name is 
observable. Instead, the requires directive in a module declaration (§7.7.1) performs its 
own validation of the module name, while the exports and opens directives (§7.7.2) are 
tolerant of non-existent module names. 


The meaning of a name classified as a PackageName is determined as follows. 


6.5.3.1 Simple Package Names 


Ifa package name consists of a single /dentifier, then the identifier must occur in the 
scope of exactly one declaration of a top level package with this name (§6.3), and 
that package must be uniquely visible to the current module (§7.4.3), or a compile- 
time error occurs. The meaning of the package name is that package. 


6.5.3.2 Qualified Package Names 


If a package name is of the form Q. Ia, then Q must also be a package name. The 
package name Q.Id names a package that is the member named ra within the 
package named by o. 


If 9. rd does not name a package that is uniquely visible to the current module 
(§7.4.3), then a compile-time error occurs. 


6.5.4 Meaning of PackageOrTypeNames 


6.5.4.1 Simple PackageOrTypeNames 


If the PackageOrTypeName, 0, is a valid Typeldentifier and occurs in the scope of 
a type named o, then the PackageOrTypeName is reclassified as a TypeName. 


Otherwise, the PackageOrTypeName is reclassified as a PackageName. The 
meaning of the PackageOrTypeName is the meaning of the reclassified name. 


6.5.4.2 Qualified PackageOrTypeNames 


Given a qualified PackageOrTypeName of the form Q.fa, if Id is a valid 
Typeldentifier and the type or package denoted by a has a member type named Ia, 
then the qualified PackageOrTypeName name is reclassified as a TypeName. 
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Otherwise, it is reclassified as a PackageName. The meaning of the qualified 
PackageOrTypeName is the meaning of the reclassified name. 


6.5.5 Meaning of Type Names 


The meaning of a name classified as a TypeName is determined as follows. 


6.5.5.1 Simple Type Names 


If a type name consists of a single /dentifier, then the identifier must occur in the 
scope of exactly one declaration of a type with this name (§6.3), or a compile-time 
error occurs. The meaning of the type name is that type. 


6.5.5.2 Qualified Type Names 


If a type name is of the form Q. Id, then Q must be either the name of a type in a 
package uniquely visible to the current module, or the name of a package uniquely 
visible to the current module (§7.4.3). 


If ra names exactly one accessible type ($6.6) that is a member of the type or 
package denoted by og, then the qualified type name denotes that type. 


If radoes not name a member type within o (§8.5, $9.5), or the member type named 
Idwithin ois not accessible (§6.6), or Tdnames more than one member type within 
Q, then a compile-time error occurs. 


Example 6.5.5.2-1. Qualified Type Names 


class Test { 
public static void main(String[] args) { 
java.util.Date date = 
new java.util.Date (System.currentTimeMillis()); 
System.out.println(date.toLocaleString()); 


} 
This program produced the following output the first time it was run: 
Sun Jan 21 22:56:29 1996 
In this example, the name java.util.Date must denote a type, so we first use the 


procedure recursively to determine if java.util is an accessible type or a package, which 
it is, and then look to see if the type Date is accessible in this package. 
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6.5.6 Meaning of Expression Names 


The meaning of a name classified as an ExpressionName is determined as follows. 


6.5.6.1 Simple Expression Names 


If an expression name consists of a single /dentifier, then there must be exactly one 
declaration denoting either a local variable, formal parameter, or field in scope at 
the point at which the /dentifier occurs. Otherwise, a compile-time error occurs. 


If the declaration denotes an instance variable (§8.3.1.1), the expression name must 
appear within an instance method (§8.4.3.2), instance variable initializer ($8.3.2), 
instance initializer ($8.6), or constructor (§8.8). If the expression name appears 
within a class method, class variable initializer, or static initializer (§8.7), then a 
compile-time error occurs. 


If the declaration declares a final variable which is definitely assigned before the 
simple expression, the meaning of the name is the value of that variable. Otherwise, 
the meaning of the expression name is the variable declared by the declaration. 


If the expression name appears in an assignment context, invocation context, or 
casting context, then the type of the expression name is the declared type of the 
field, local variable, or parameter after capture conversion (§5.1.10). 


Otherwise, the type of the expression name is the declared type of the field, local 
variable or parameter. 


That is, if the expression name appears "on the right hand side", its type is subject to capture 
conversion. If the expression name is a variable that appears "on the left hand side", its type 
is not subject to capture conversion. 


Example 6.5.6.1-1. Simple Expression Names 


class Test { 
static int v; 
static final int f = 3; 
public static void main(String[] args) { 


int i; 

i= 1; 

Ves 

£ = 33; // compile-time error 
System.out.println(i +" "+v+" "+ £); 


In this program, the names used as the left-hand-sides in the assignments to i, v, and £ 
denote the local variable i, the field v, and the value of £ (not the variable £, because f is 
a final variable). The example therefore produces an error at compile time because the 
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last assignment does not have a variable as its left-hand side. If the erroneous assignment 
is removed, the modified code can be compiled and it will produce the output: 


123 


6.5.6.2 Qualified Expression Names 


If an expression name is of the form Q. Ia, then g has already been classified as a 
package name, a type name, or an expression name. 


If ois a package name, then a compile-time error occurs. 
If ois a type name that names a class type ($8 (Classes)), then: 


¢ If there is not exactly one accessible ($6.6) member of the class type that is a 
field named ra, then a compile-time error occurs. 


¢ Otherwise, if the single accessible member field is not a class variable (that is, it 
is not declared static), then a compile-time error occurs. 


¢ Otherwise, if the class variable is declared final, then Q. Id denotes the value 
of the class variable. 


The type of the expression Q. Id is the declared type of the class variable after 
capture conversion (§5.1.10). 


If Q. Id appears in a context that requires a variable and not a value, then a 
compile-time error occurs. 


¢ Otherwise, Q. Id denotes the class variable. 


The type of the expression Q. Id is the declared type of the class variable after 
capture conversion (§5.1.10). 


Note that this clause covers the use of enum constants (§8.9), since these always have 
a corresponding final class variable. 


If Qis a type name that names an interface type (§9 (Unterfaces)), then: 


¢ If there is not exactly one accessible ($6.6) member of the interface type that is 
a field named ra, then a compile-time error occurs. 


¢ Otherwise, Q. rd denotes the value of the field. 


The type of the expression Q. Id is the declared type of the field after capture 
conversion (§5.1.10). 


If Q. Id appears in a context that requires a variable and not a value, then a 
compile-time error occurs. 
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If ois an expression name, let rT be the type of the expression o: 
¢ If ris not a reference type, a compile-time error occurs. 


¢ If there is not exactly one accessible ($6.6) member of the type r that is a field 


named ra, then a compile-time error occurs. 
Otherwise, if this field is any of the following: 
— A field of an interface type 


— A final field of a class type (which may be either a class variable or an 
instance variable) 


— The final field Length of an array type (§10.7) 


then Q. rddenotes the value of the field, unless it appears in a context that requires 
a variable and the field is a definitely unassigned blank final field, in which 
case it yields a variable. 


The type of the expression Q. Id is the declared type of the field after capture 
conversion (§5.1.10). 


If Q. Id appears in a context that requires a variable and not a value, and the field 
denoted by o. rdis definitely assigned, then a compile-time error occurs. 


Otherwise, Q. rd denotes a variable, the field td of class Tr, which may be either 
a class variable or an instance variable. 


The type of the expression Q. Id is the type of the field member after capture 
conversion (§5.1.10). 


Example 6.5.6.2-1. Qualified Expression Names 


class Point { 
int x, y; 
static int nPoints; 


} 


class Test { 
public static void main(String[] args) { 
int i = 0; 
i.xtt; // compile-time error 
Point p = new Point (); 
p-nPoints(); // compile-time error 


} 


This program encounters two compile-time errors, because the int variable i has no 
members, and because nPoints is not a method of class Point. 
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Example 6.5.6.2-2. Qualifying an Expression with a Type Name 


Note that expression names may be qualified by type names, but not by types in general. 
A consequence is that it is not possible to access a class variable through a parameterized 
type. For example, given the code: 

class Foox<T> { 

public static int classVar = 42; 

} 
the following assignment is illegal: 

Foo<String>.classVar = 91; // illegal 
Instead, one writes: 

Foo.classVar = 91; 
This does not restrict the Java programming language in any meaningful way. Type 
parameters may not be used in the types of static variables, and so the type arguments 
of a parameterized type can never influence the type of a static variable. Therefore, no 
expressive power is lost. The type name Foo appears to be a raw type, but it is not; rather, 


it is the name of the non-generic type Foo whose static member is to be accessed ($6.1). 
Since there is no use of a raw type, there are no unchecked warnings. 


6.5.7 Meaning of Method Names 


The meaning of a name classified as a MethodName is determined as follows. 


6.5.7.1 Simple Method Names 


A simple method name appears in the context of a method invocation expression 
($15.12). The simple method name consists of a single /dentifier which specifies 
the name of the method to be invoked. The rules of method invocation require that 
the Identifier either denotes a method that is in scope at the point of the method 
invocation, or denotes a method imported by a single-static-import declaration or 


static-import-on-demand declaration (§7.5.3, §7.5.4). 


Example 6.5.7.1-1. Simple Method Names 


The following program demonstrates the role of scoping when determining which method 
to invoke. 


class Super { 
void £2(String s) {} 
void £3(String s) {} 
void f3(int il, int i2) {} 


6.5 


165 


6.6 Access Control NAMES 


class Test { 
void fl(int i) {} 
void f2(int i) {} 
void f£3(int i) {} 


void m() { 
new Super() { 
{ 
£1(0); // OK, resolves to Test.f1(int) 
£2(0); // compile-time error 
£3(0); // compile-time error 


For the invocation £1(0), only one method named f1 is in scope. It is the method 
Test.f1 (int), whose declaration is in scope throughout the body of Test including the 
anonymous class declaration. §15.12.1 chooses to search in class Test since the anonymous 
class declaration has no member named f1. Eventually, Test .f1 (int) is resolved. 


For the invocation £2 (0), two methods named £2 are in scope. First, the declaration of 
the method Super. £2 (String) is in scope throughout the anonymous class declaration. 
Second, the declaration of the method Test . £2 (int) is in scope throughout the body of 
Test including the anonymous class declaration. (Note that neither declaration shadows 
the other, because at the point where each is declared, the other is not in scope.) 
§15.12.1 chooses to search in class Super because it has a member named £2. However, 
Super. f2(String) is not applicable to £2 (0), so acompile-time error occurs. Note that 
class Test is not searched. 


For the invocation £3(0), three methods named £3 are in scope. First and second, 
the declarations of the methods Super. £3(String) and Super.f£3(int,int) are in 
scope throughout the anonymous class declaration. Third, the declaration of the method 
Test.£3(int) is in scope throughout the body of Test including the anonymous class 
declaration. §15.12.1 chooses to search in class Super because it has a member named £3. 
However, Super. f3 (String) and Super. f3 (int, int) are not applicable to £3 (0), so 
a compile-time error occurs. Note that class Test is not searched. 


Choosing to search a nested class's superclass hierarchy before the lexically enclosing scope 
is called the "comb rule" (§15.12.1). 


6.6 Access Control 


The Java programming language provides mechanisms for access control, to 
prevent the users of a package or class from depending on unnecessary details of the 
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implementation of that package or class. If access is permitted, then the accessed 
entity is said to be accessible. 


Note that accessibility is a static property that can be determined at compile time; 
it depends only on types and declaration modifiers. 


Qualified names are a means of access to members of packages and reference 
types. When the name of such a member is classified from its context (§6.5.1) as a 
qualified type name (denoting a member of a package or reference type, §6.5.5.2) 
or a qualified expression name (denoting a member of a reference type, §6.5.6.2), 
access control is applied. 


For example, a single-type-import declaration uses a qualified type name (§7.5.1), so 
the named type must be accessible from the compilation unit containing the import 
declaration. As another example, a class declaration may use a qualified type name for a 
superclass (§8.1.5), so again the named type must be accessible. 


Some obvious expressions are "missing" from context classification in §6.5.1: field access 
on a Primary (§15.11.1), method invocation on a Primary (§15.12), method reference via 
a Primary (§15.13), and the instantiated class in a qualified class instance creation (§15.9). 
Each of these expressions uses identifiers, rather than names, for the reason given in §6.2. 
Consequently, access control to members (whether fields, methods, or types) is applied 
explicitly by field access expressions, method invocation expressions, method reference 
expressions, and qualified class instance creation expressions. (Note that access to a field 
may also be denoted by a qualified name occuring as a postfix expression.) 


In addition, many statements and expressions allow the use of types rather than type 
names. For example, a class declaration may use a parameterized type (§4.5) to denote 
a superclass. Because a parameterized type is not a qualified type name, it is necessary 
for the class declaration to explicitly perform access control for the denoted superclass. 
Consequently, most of the statements and expressions that provide contexts in §6.5.1 to 
classify a TypeName also perform their own access control checks. 


Beyond access to members of a package or reference type, there is the matter of access 
to constructors of a reference type. Access control must be checked when a constructor 
is invoked explicitly or implicitly. Consequently, access control is checked by an explicit 
constructor invocation statement (§8.8.7.1) and by a class instance creation expression 
(§15.9.3). Such checks are necessary because §6.5.1 has no mention of explicit constructor 
invocation statements (because they reference constructor names indirectly) and is unaware 
of the distinction between the class type denoted by an unqualified class instance creation 
expression and a constructor of that class type. Also, constructors do not have qualified 
names, so we cannot rely on access control being checked during classification of qualified 
type names. 


Accessibility affects inheritance of class members (§8.2), including hiding and method 
overriding (§8.4.8.1). 
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6.6.1 Determining Accessibility 


¢ If a top level class or interface type is declared public and is a member of a 
package that is exported by a module, then the type may be accessed by any code 
in the same module, and by any code in another module to which the package 
is exported, provided that the compilation unit in which the type is declared is 
visible to that other module (§7.3). 


¢ If a top level class or interface type is declared public and is a member of a 
package that is not exported by a module, then the type may be accessed by any 
code in the same module. 


¢ If atop level class or interface type is declared with package access, then it may 
be accessed only from within the package in which it is declared. 


A top level class or interface type declared without an access modifier implicitly 
has package access. 


¢« A member (class, interface, field, or method) of a reference type, or a constructor 
of a class type, is accessible only if the type is accessible and the member or 
constructor is declared to permit access: 


— If the member or constructor is declared public, then access is permitted. 
All members of interfaces lacking access modifiers are implicitly public. 


— Otherwise, if the member or constructor is declared protected, then access is 
permitted only when one of the following is true: 


» Access to the member or constructor occurs from within the package 
containing the class in which the protected member or constructor is 
declared. 


> Access is correct as described in §6.6.2. 


— Otherwise, if the member or constructor is declared with package access, then 
access is permitted only when the access occurs from within the package in 
which the type is declared. 


A class member or constructor declared without an access modifier implicitly 
has package access. 


— Otherwise, the member or constructor is declared private, and access is 
permitted if and only if it occurs within the body of the top level type ($7.6) 
that encloses the declaration of the member or constructor. 


e An array type is accessible if and only if its element type is accessible. 
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Example 6.6-1. Access Control 
Consider the two compilation units: 


package points; 
class PointVec { Point[] vec; } 


and: 


package points; 
public class Point { 
protected int x, y; 
public void move(int dx, int dy) { x += dx; y += dy; 
public int getX() { return x; } 
public int getY() { return y; } 


which declare two class types in the package points: 


¢ The class type PointVec is not public and not part of the public interface of the 


package points, but rather can be used only by other classes in the package. 


¢ The class type Point is declared public and is available to other packages. It is part 


of the public interface of the package points. 


¢ The methods move, get x, and get of the class Point are declared public and so are 


available to any code that uses an object of type Point. 


¢ The fields x and y are declared protected and are accessible outside the package 
points only in subclasses of class Point, and only when they are fields of objects that 


are being implemented by the code that is accessing them. 


See §6.6.2 for an example of how the protected access modifier limits access. 


Example 6.6-2. Access to public Fields, Methods, and Constructors 


A public class member or constructor is accessible throughout the package where it is 
declared and from any other package, provided the package in which it is declared is 


observable (§7.4.3). For example, in the compilation unit: 


package points; 
public class Point { 
int x, y; 
public void move(int dx, int dy) { 
x += dx; y += dy; 
movest+t; 
} 


public static int moves = 0; 
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the public class Point has as public members the move method and the moves field. 
These public members are accessible to any other package that has access to package 
points. The fields x and y are not public and therefore are accessible only from within 
the package points. 


Example 6.6-3. Access to public and Non-public Classes 


If aclass lacks the public modifier, access to the class declaration is limited to the package 
in which it is declared (§6.6). In the example: 


package points; 
public class Point { 
public int x, y; 
public void move(int dx, int dy) { x += dx; y += dy; } 
} 
class PointList { 
Point next, prev; 


two classes are declared in the compilation unit. The class Point is available outside 
the package points, while the class PointList is available for access only within the 
package. Thus a compilation unit in another package can access points.Point, either by 
using its fully qualified name: 


package pointsUser; 
class Testl { 
public static void main(String[] args) { 
points.Point p = new points.Point(); 
System.out.printlin(p.x + " "+ p.y); 


or by using a single-type-import declaration ($7.5. 1) that mentions the fully qualified name, 
so that the simple name may be used thereafter: 


package pointsUser; 
import points.Point; 
class Test2 { 
public static void main(String[] args) { 
Point p = new Point (); 
System.out.println(p.x + " "+ p.y); 


However, this compilation unit cannot use or import points.PointList, which is not 
declared public and is therefore inaccessible outside package points. 
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Example 6.6-4. Access to Package-Access Fields, Methods, and Constructors 


If none of the access modifiers public, protected, or private are specified, a class 
member or constructor has package access: it is accessible throughout the package that 
contains the declaration of the class in which the class member is declared, but the class 
member or constructor is not accessible in any other package. 


If a public class has a method or constructor with package access, then this method or 
constructor is not accessible to or inherited by a subclass declared outside this package. 


For example, if we have: 


package points; 
public class Point { 
public int x, y? 
void move(int dx, int dy) { x += dx; y += dy; } 
public void moveAlso(int dx, int dy) { move(dx, dy); } 


then a subclass in another package may declare an unrelated move method, with the same 
signature (§8.4.2) and return type. Because the original move method is not accessible from 
package morepoints, super may not be used: 


package morepoints; 
public class PlusPoint extends points.Point { 
public void move(int dx, int dy) { 
super.move (dx, dy); // compile-time error 
moveAlso(dx, dy); 


Because move of Point is not overridden by move in PlusPoint, the method moveAlso 
in Point never calls the method move in PlusPoint. Thus if you delete the super .move 
call from PlusPoint and execute the test program: 


import points.Point; 
import morepoints.PlusPoint; 
class Test { 
public static void main(String[] args) { 
PlusPoint pp = new PlusPoint(); 
pp.move(1, 1); 


it terminates normally. If move of Point were overridden by move in PlusPoint, then 
this program would recurse infinitely, until a StackOverflowError occurred. 
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Example 6.6-5. Access to private Fields, Methods, and Constructors 


A private class member or constructor is accessible only within the body of the top level 
class (§7.6) that encloses the declaration of the member or constructor. It is not inherited 
by subclasses. In the example: 


class Point { 

Point() { setMasterID(); } 

Antex, yy 

private int ID; 

private static int masterID = 0; 

private void setMasterID() { ID = masterID++; } 
} 


the private members ID, masterID, and setMasterID may be used only within the body 
of class Point. They may not be accessed by qualified names, field access expressions, or 
method invocation expressions outside the body of the declaration of Point. 


See §8.8.10 for an example that uses a private constructor. 


6.6.2 Details on protected Access 


A protected member or constructor of an object may be accessed from outside 
the package in which it is declared only by code that is responsible for the 
implementation of that object. 


6.6.2.1 Access to a protected Member 


Let c be the class in which a protected member is declared. Access is permitted 
only within the body of a subclass s of c. 


A subclass s is regarded as being responsible for the implementation of objects of class c. 
Depending on c's accessibility, s may be declared in the same package as c, or in different 
package of the same module as c, or in a package of a different module entirely. 


In addition, access to an instance field or instance method is permitted based on the 
form of the qualified name, field access expression (§15.11), method invocation 
expression (§15.12), or method reference expression (§15.13): 


e If the access is by (i) a qualified name of the form ExpressionName.Id or 
TypeName. Id, or (ii) a field access expression of the form Primary.fId, then 
access to the instance field rd is permitted if and only if the qualifying type is 
sora subclass of s. 


The qualifying type is the type of the ExpressionName or Primary, or the type 
denoted by TypeName. 
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e If the access is by (i) a method invocation expression of the form 
ExpressionName.Id(...) Of TypeName.Id(...) Of Primary.Id(...), Or (ii) a 
method reference expression of the form ExpressionName :: IdOf Primary :: 
Id Or ReferenceType :: Id, then access to the instance method Id is permitted 
if and only if the qualifying type is s or a subclass of s. 


The qualifying type is the type of the ExpressionName or Primary, or the type 
denoted by TypeName or ReferenceType. 


More information about access to protected members can be found in Checking Access 
to Protected Members in the Java Virtual Machine by Alessandro Coglio, in the Journal 
of Object Technology, October 2005. 


6.6.2.2 Access to a protected Constructor 


Let c be the class in which a protected constructor is declared and let s be the 
innermost class in whose declaration the use of the protected constructor occurs. 
Then: 


e If the access is by a superclass constructor invocation super(...), or a 
qualified superclass constructor invocation E.super(...), where Eis a Primary 
expression, then the access is permitted. 


e If the access is by an anonymous class instance creation expression new C(...) 
{...}, or a qualified anonymous class instance creation expression E.new 
C(...){...}, where Eis a Primary expression, then the access is permitted. 


e If the access is by a simple class instance creation expression new C(...), ora 
qualified class instance creation expression E.new C(...), where Zis a Primary 
expression, or a method reference expression c :: new, where cis a ClassType, 
then the access is not permitted. A protected constructor can be accessed by a 
class instance creation expression (that does not declare an anonymous class) or a 
method reference expression only from within the package in which it is defined. 


Example 6.6.2-1. Access to protected Fields, Methods, and Constructors 


Consider this example, where the points package declares: 


package points; 
public class Point { 
protected int x, y; 
void warp(threePoint.Point3d a) { 
if (a.z > 0) // compile-time error: cannot access a.z 
a.delta(this); 
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and the threePoint package declares: 


package threePoint; 
import points.Point; 
public class Point3d extends Point { 
protected int z; 
public void delta(Point p) { 
p.x += this.x; // compile-time error: cannot access p.x 
p.y += this.y; // compile-time error: cannot access p.y 
} 
public void delta3d(Point3d q) { 
q.x += this.x; 
q.y += this.y; 
q.z += this.z; 


A compile-time error occurs in the method delta here: it cannot access the protected 
members x and y of its parameter p, because while Point3d (the class in which the 
references to fields x and y occur) is a subclass of Point (the class in which x and y are 
declared), it is not involved in the implementation of a Point (the type of the parameter p). 
The method delta3d can access the protected members of its parameter q, because the 
class Point 3d is a subclass of Point and is involved in the implementation of a Point 3d. 


The method delta could try to cast (§5.5, §15.16) its parameter to be a Point 3d, but this 
cast would fail, causing an exception, if the class of p at run time were not Point3d. 


A compile-time error also occurs in the method warp: it cannot access the protected 
member z of its parameter a, because while the class Point (the class in which the reference 
to field z occurs) is involved in the implementation of a Point 3d (the type of the parameter 
a), it is not a subclass of Point 3d (the class in which z is declared). 


6.7 Fully Qualified Names and Canonical Names 


Every primitive type, named package, top level class, and top level interface has 
a fully qualified name: 


¢ The fully qualified name of a primitive type is the keyword for that primitive 
type, namely byte, short, char, int, long, float, double, OF boolean. 


¢ The fully qualified name of a named package that is not a subpackage of anamed 
package is its simple name. 


¢ The fully qualified name of a named package that is a subpackage of another 
named package consists of the fully qualified name of the containing package, 
followed by ".", followed by the simple (member) name of the subpackage. 
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¢ The fully qualified name of a top level class or top level interface that is declared 
in an unnamed package is the simple name of the class or interface. 


¢ The fully qualified name of a top level class or top level interface that is declared 
in a named package consists of the fully qualified name of the package, followed 
by ".", followed by the simple name of the class or interface. 


Each member class, member interface, and array type may have a fully qualified 
name: 


¢ A member class or member interface mu of another class or interface c has a fully 
qualified name if and only if c has a fully qualified name. 


In that case, the fully qualified name of uconsists of the fully qualified name of 
c, followed by ".", followed by the simple name of ™. 


e An array type has a fully qualified name if and only if its element type has a 
fully qualified name. 


In that case, the fully qualified name of an array type consists of the fully 
qualified name of the component type of the array type followed by "[1". 


A local class or anonymous class does not have a fully qualified name. 


Every primitive type, named package, top level class, and top level interface has 
a canonical name: 


¢ For every primitive type, named package, top level class, and top level interface, 
the canonical name is the same as the fully qualified name. 


Each member class, member interface, and array type may have a canonical name: 


¢ A member class or member interface ™ declared in another class or interface c 
has a canonical name if and only if c has a canonical name. 


In that case, the canonical name of wconsists of the canonical name of c, followed 
by ".", followed by the simple name of ™. 


e An array type has a canonical name if and only if its component type has a 
canonical name. 


In that case, the canonical name of the array type consists of the canonical name 
of the component type of the array type followed by "[1". 


A local class or anonymous class does not have a canonical name. 


Example 6.7-1. Fully Qualified Names 


¢ The fully qualified name of the type long is "long". 
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¢ The fully qualified name of the package java.lang is "java.lang" because it is 
subpackage lang of package java. 


¢ The fully qualified name of the class Object, which is defined in the package 
java.lang, is "java.lang.Object". 


¢ The fully qualified name of the interface Enumeration, which is defined in the package 
java.util, is "java.util.Enumeration". 


¢ The fully qualified name of the type "array of double" is "double[]". 
¢ The fully qualified name of the type "array of array of array of array of String" is 
"Java.lang.String[][]{[]{]". 


In the code: 


package points; 
class Point { int x, y; } 
class PointVec { Point[] vec; } 


the fully qualified name of the type Point is "points.Point"; the fully qualified name 
of the type PointVec is "points.PointVec"; and the fully qualified name of the type of 
the field vec of class PointVec is "points.Point[]". 


Example 6.7-2. Fully Qualified Names v. Canonical Name 


The difference between a fully qualified name and a canonical name can be seen in code 
such as: 


package p; 
class O1 { class I {} } 
class O02 extends O1 {} 


Both p.01.1 and p.02.1 are fully qualified names that denote the member class 1, but 
only p.O1.1 is its canonical name. 


176 


ere 


Packages and Modules 


PROGRAMS are organized as sets of packages. The members of a package ($7.1) 
are class and interface types, which are declared in compilation units of the 
package, and subpackages, which may contain compilation units and subpackages 
of their own. 


Each package has its own set of names for types, which helps to prevent name 
conflicts. The naming structure for packages is hierarchical. 


If a set of packages is sufficiently cohesive, then the packages may be grouped into 
a module. A module categorizes some or all of its packages as exported, which 
means their types may be accessed from code outside the module. If a package is 
not exported by a module, then only code inside the module may access its types. 
Furthermore, if code in a module wishes to access the packages exported by another 
module, then the first module must explicitly depend on the second module. Thus, 
a module controls how its packages use other modules (by specifying dependences) 
and controls how other modules use its packages (by specifying which of its 
packages are exported). 


Modules and packages may be stored in a file system or in a database ($7.2). 
Modules and packages that are stored in a file system may have certain constraints 
on the organization of their compilation units to allow a simple implementation to 
find module and type declarations easily. 


Code in a compilation unit automatically has access to all types declared in its 
package and also automatically imports all of the public types declared in the 
predefined package java. lang. 


A top level type is accessible ($6.6) outside the package that declares it only if 
the type is declared public. A top level type is accessible outside the module that 
declares it only if the type is declared public and is a member of an exported 
package. A type that is declared public but is not a member of an exported package 
is accessible only to code inside the module. 
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For small programs and casual development, a package can be unnamed (§7.4.2) or 
have a simple name, but if code is to be widely distributed, unique package names 
should be chosen using qualified names. This can prevent the conflicts that would 
otherwise occur if two development groups happened to pick the same package 
name and these packages were later to be used in a single program. 


7.1 Package Members 


The members of a package are its subpackages and all the top level class types 
($7.6, §8 (Classes)) and top level interface types (§9 Unterfaces)) declared in all 
the compilation units ($7.3) of the package. 


For example, in the Java SE Platform API: 


e The package java has subpackages awt, applet, io, lang, net, and util, but no 
compilation units. 


¢ The package java.awt has a subpackage named image, as well as a number of 
compilation units containing declarations of class and interface types. 


If the fully qualified name (86.7) of a package is P, and ¢ is a subpackage of P, 
then P.q is the fully qualified name of the subpackage, and furthermore denotes 
a package. 


A package may not contain two members of the same name, or a compile-time 
error results. 


Here are some examples: 


¢ Because the package java.awt has a subpackage image, it cannot (and does not) 
contain a declaration of a class or interface type named image. 


¢ If there is a package named mouse and a member type Button in that package (which 
then might be referred to as mouse. Button), then there cannot be any package with the 
fully qualified name mouse. Button or mouse.Button.Click. 


¢ Ifcom.nighthacks. java. jag is the fully qualified name of a type, then there cannot 
be any package whose fully qualified name is either com.nighthacks. java. jag or 
com.nighthacks.java.jag.scrabble 


It is however possible for members of different packages to have the same simple name. 
For example, it is possible to declare a package: 


package vector; 
public class Vector { Object[] vec; } 
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that has as a member a public class named Vector, even though the package java.util 
also declares a class named Vector. These two class types are different, reflected by the 
fact that they have different fully qualified names (§6.7). The fully qualified name of this 
example Vector is vector.Vector, whereas java.util.Vector is the fully qualified 
name of the Vector class included in the Java SE Platform. Because the package vector 
contains a class named Vector, it cannot also have a subpackage named Vector. 


The hierarchical naming structure for packages is intended to be convenient for 
organizing related packages in a conventional manner, but has no significance in 
itself other than the prohibition against a package having a subpackage with the 
same simple name as a top level type ($7.6) declared in that package. 


For example, there is no special access relationship between a package named oliver and 
another package named oliver.twist, or between packages named evelyn.wood and 
evelyn.waugh. That is, the code in a package named oliver. twist has no better access 
to the types declared within package oliver than code in any other package. 


7.2 Host Support for Modules and Packages 


Each host system determines how modules, packages, and compilation units are 
created and stored. 


Each host system determines which compilation units are observable in a 
particular compilation (§7.3). Each host system also determines which observable 
compilation units are associated with a module. The observability of compilation 
units associated with a module determines which modules are observable (§7.7.3) 
and which packages are visible within those modules (§7.4.3). 


The host system is free to determine that a compilation unit which contains a module 
declaration is not, in fact, observable, and thus is not associated with the module declared 
therein. This enables a compiler to choose which directory on a modulesourcepath Is 
"really" the embodiment of a given module. However, if the host system determines that a 
compilation unit which contains a module declaration is observable, then §7.4.3 mandates 
that the compilation unit must be associated with the module declared therein, and not with 
any other module. 


The host system is free to determine that a compilation unit which contains a type 
declaration is (first) observable and (second) associated with an unnamed module or an 
automatic module - despite no declaration of an unnamed or automatic module existing in 
any compilation unit, observable or otherwise. 


In simple implementations of the Java SE Platform, packages and compilation units 
may be stored in a local file system. Other implementations may store them using 
a distributed file system or some form of database. 
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If a host system stores packages and compilation units in a database, then the 
database must not impose the optional restrictions ($7.6) on compilation units 
permissible in file-based implementations. 


For example, a system that uses a database to store packages may not enforce a maximum 
of one public class or interface per compilation unit. 


Systems that use a database must, however, provide an option to convert a 
program to a form that obeys the restrictions, for purposes of export to file-based 
implementations. 


As an extremely simple example of storing packages in a file system, all the packages 
and source and binary code in a project might be stored in a single directory and its 
subdirectories. Each immediate subdirectory of this directory would represent a top level 
package, that is, one whose fully qualified name consists of a single simple name. Each 
further level of subdirectory would represent a subpackage of the package represented by 
the containing directory, and so on. 


The directory might contain the following immediate subdirectories: 


com 
gls 
jag 
java 
wn 4 


where directory java would contain the Java SE Platform packages; the directories jag, 
gls, and wnj might contain packages that three of the authors of this specification created 
for their personal use and to share with each other within this small group; and the directory 
com would contain packages procured from companies that used the conventions described 
in §6.1 to generate unique names for their packages. 


Continuing the example, the directory java would contain, among others, the following 
subdirectories: 


applet 
awt 

io 
lang 
net 
util 


corresponding to the packages java.applet, java.awt, java.io, java.lang, 
java.net, and java.util that are defined as part of the Java SE Platform API. 


Still continuing the example, if we were to look inside the directory util, we might see 
the following files: 
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BitSet.java Observable. java 
BitSet.class Observable.class 
Date. java Observer.java 
Date.class Observer.class 


where each of the . java files contains the source for a compilation unit (§7.3) that contains 
the definition of a class or interface whose binary compiled form is contained in the 
corresponding .class file. 


Under this simple organization of packages, an implementation of the Java SE Platform 
would transform a package name into a pathname by concatenating the components of 
the package name, placing a file name separator (directory indicator) between adjacent 
components. 


For example, if this simple organization were used on an operating system where the file 
name separator is /, the package name: 


jag.scrabble.board 
would be transformed into the directory name: 
jag/scrabble/board 


A package name component or class name might contain a character that cannot correctly 
appear in a host file system's ordinary directory name, such as a Unicode character on a 
system that allows only ASCII characters in file names. As a convention, the character can 
be escaped by using, say, the @ character followed by four hexadecimal digits giving the 
numeric value of the character, as in the \uxxxx escape (§3.3). 


Under this convention, the package name: 
children.activities.crafts.papierM\u00e2ch\u00e9 
which can also be written using full Unicode as: 
children.activities.crafts.papierMaché 

might be mapped to the directory name: 
children/activities/crafts/papierM@00e2ch@00e9 


If the @ character is not a valid character in a file name for some given host file system, 
then some other character that is not valid in a identifier could be used instead. 
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7.3 Compilation Units 


CompilationUnit is the goal symbol (§2.1) for the syntactic grammar (§2.3) of Java 
programs. It is defined by the following production: 


CompilationUnit: 
Ordinary CompilationUnit 
ModularCompilationUnit 


OrdinaryCompilationUnit: 
[PackageDeclaration] {ImportDeclaration} {TypeDeclaration} 


ModularCompilationUnit: 
{ImportDeclaration} ModuleDeclaration 


An ordinary compilation unit consists of three parts, each of which is optional: 


¢ A package declaration (§7.4), giving the fully qualified name (§6.7) of the 
package to which the compilation unit belongs. 


A compilation unit that has no package declaration is part of an unnamed 
package (§7.4.2). 


* import declarations (§7.5) that allow types from other packages and static 
members of types to be referred to using their simple names. 


¢ Top level type declarations ($7.6) of class and interface types. 


A modular compilation unit consists of a module declaration (§7.7), optionally 
preceded by import declarations. The import declarations allow types from 
packages in this module and other modules, as well as stat ic members of types, 
to be referred to using their simple names within the module declaration. 


Every compilation unit implicitly imports every public type name declared in 
the predefined package java.lang, as if the declaration import java.lang.*; 
appeared at the beginning of each compilation unit immediately after any package 
declaration. As a result, the names of all those types are available as simple names 
in every compilation unit. 


The host system determines which compilation units are observable, except for the 
compilation units in the predefined package java and its subpackages lang and io, 
which are all always observable. 


Each observable compilation unit may be associated with a module, as follows: 
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¢ The host system may determine that an observable ordinary compilation unit is 
associated with a module chosen by the host system, except for (i) the ordinary 
compilation units in the predefined package java and its subpackages lang and 
io, which are all associated with the java.base module, and (ii) any ordinary 
compilation unit in an unnamed package, which is associated with a module as 
specified in §7.4.2. 


¢ The host system must determine that an observable modular compilation unit is 
associated with the module declared by the modular compilation unit. 


The observability of a compilation unit influences the observability of its package (§7.4.3), 
while the association of an observable compilation unit with a module influences the 
observability of that module (§7.7.6). 


When compiling the modular and ordinary compilation units associated with a 
module ™, the host system must respect the dependences specified in ms declaration. 
Specifically, the host system must limit the ordinary compilation units that 
would otherwise be observable, to only those that are visible to u. The ordinary 
compilation units that are visible to mw are the observable ordinary compilation 
units associated with the modules that are read by mu. The modules read by 
are given by the result of resolution, as described in the java.lang.module 
package specification, with mw as the only root module. The host system must 
perform resolution to determine the modules read by m™ it is a compile-time error if 
resolution fails for any of the reasons described in the java.lang.module package 
specification. 


The readability relation is reflexive, so m reads itself, and thus all of the modular and 
ordinary compilation units associated with mare visible to M. 


The modules read by ™ drive the packages that are uniquely visible to m (§7.4.3), which in 
turn drives both the top level packages in scope and the meaning of package names for code 
in the modular and ordinary compilation units associated with m (86.3, §6.5.3, §6.5.5). 


The rules above ensure that package/type names used in annotations in a modular 
compilation unit (in particular, annotations applied to the module declaration) are 
interpreted as if they appeared in an ordinary compilation unit associated with the module. 


Types declared in different ordinary compilation units can refer to each other, 
circularly. A Java compiler must arrange to compile all such types at the same time. 
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7.4 Package Declarations 


A package declaration appears within an ordinary compilation unit to indicate the 
package to which the compilation unit belongs. 


7.4.1 Named Packages 


A package declaration in an ordinary compilation unit specifies the name (§6.2) 
of the package to which the compilation unit belongs. 


PackageDeclaration: 
{PackageModifier} package Identifier { . Identifier} ; 


PackageModifier: 
Annotation 


The package name mentioned in a package declaration must be the fully qualified 
name of the package (§6.7). 


The scope and shadowing of a package declaration is specified in $6.3 and §6.4. 


The rules for annotation modifiers on a package declaration are specified in §9.7.4 
and §9.7.5. 


At most one annotated package declaration is permitted for a given package. 


The manner in which this restriction is enforced must, of necessity, vary from 
implementation to implementation. The following scheme is strongly recommended for 
file-system-based implementations: The sole annotated package declaration, if it exists, is 
placed in a source file called package-info. java in the directory containing the source 
files for the package. This file does not contain the source for a class called package-info; 
indeed it would be illegal for it to do so, as package-info is nota legal identifier. Typically 
package-info. java contains only a package declaration, preceded immediately by the 
annotations on the package. While the file could technically contain the source code for 
one or more classes with package access, it would be very bad form. 


It is recommended that package-info.java, if it is present, take the place of 
package.html for javadoc and other similar documentation generation systems. If 
this file is present, the documentation generation tool should look for the package 
documentation comment immediately preceding the (possibly annotated) package 
declaration in package-info. Java. In this way, package-info.java becomes the 
sole repository for package-level annotations and documentation. If, in future, it becomes 
desirable to add any other package-level information, this file should prove a convenient 
home for this information. 
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7.4.2 Unnamed Packages 


An ordinary compilation unit that has no package declaration, but has at least one 
other kind of declaration, is part of an unnamed package. 


Unnamed packages are provided by the Java SE Platform principally for 
convenience when developing small or temporary applications or when just 
beginning development. 


An unnamed package cannot have subpackages, since the syntax of a package 
declaration always includes a reference to a named top level package. 


An implementation of the Java SE Platform must support at least one unnamed 
package. An implementation may support more than one unnamed package, but 
is not required to do so. Which ordinary compilation units are in each unnamed 
package is determined by the host system. 


The host system must associate ordinary compilation units in an unnamed package 
with an unnamed module (§7.7.5), not a named module. 


Example 7.4.2-1. Unnamed Package 


The compilation unit: 


class FirstCall { 
public static void main(String[] args) { 
System.out.println("Mr. Watson, come here. " 
+ "IT want you."); 


} 
defines a very simple compilation unit as part of an unnamed package. 


In implementations of the Java SE Platform that use a hierarchical file system for storing 
packages, one typical strategy is to associate an unnamed package with each directory; only 
one unnamed package is observable at a time, namely the one that is associated with the 
"current working directory". The precise meaning of "current working directory" depends 
on the host system. 


7.4.3 Package Observability and Visibility 


A package is observable if and only if at least one of the following is true: 


¢ An ordinary compilation unit containing a declaration of the package is 
observable (§7.3). 


¢ A subpackage of the package is observable. 


The packages java, java.lang, and java.io are always observable. 
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One can conclude this from the rule above and from the rules of observable compilation 
units, as follows. The predefined package java.1lang declares the class Object, so the 
compilation unit for Object is always observable (§7.3). Hence, the java. lang package is 
observable, and the java package also. Furthermore, since Object is observable, the array 
type Object [] implicitly exists. Its superinterface java.io.Serializable (§10.1) also 
exists, hence the java.io package is observable. 


A package is visible to a module if and only if an ordinary compilation unit 
containing a declaration of the package is visible to m. 


Package visibility is meant to imply that a package is observable in a useful way to a given 
module. It is generally not useful to know that package P is observable merely because a 
subpackage P.Q is observable. For example, suppose P.Q is observable (in module M1) 
and P.R is observable (in module M2); then, P is observable, but where? In M1, or M2, or 
both? The question is redundant; during compilation of module N that requires only M1, it 
matters that P.Q is observable, but it does not matter that P is observable. 


A package is uniquely visible to a module mif and only if one of the following holds: 


e An ordinary compilation unit associated with » contains a declaration of the 
package, and m does not read any other module that exports the package to ™. 


¢ No ordinary compilation unit associated with m contains a declaration of the 
package, and mreads exactly one other module that exports the package to ». 


7.5 Import Declarations 


An import declaration allows a named type or a static member to be referred to 
by a simple name (§6.2) that consists of a single identifier. 


Without the use of an appropriate import declaration, the only way to refer to a 
type declared in another package, or a static member of another type, is to use 
a fully qualified name (§6.7). 


ImportDeclaration: 
SingleTypelmportDeclaration 
TypeIlmportOnDemandDeclaration 
SingleStaticImportDeclaration 
StaticImportOnDemandDeclaration 


¢ A single-type-import declaration (§7.5.1) imports a single named type, by 
mentioning its canonical name (§6.7). 
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e A type-import-on-demand declaration (§7.5.2) imports all the accessible types 
of a named type or named package as needed, by mentioning the canonical name 
of a type or package. 


¢ A single-static-import declaration (§7.5.3) imports all accessible static 
members with a given name from a type, by giving its canonical name. 


¢ A static-import-on-demand declaration ($7.5.4) imports all accessible static 
members of a named type as needed, by mentioning the canonical name of a type. 


The scope and shadowing of a type or member imported by these declarations is 
specified in §6.3 and §6.4. 


An import declaration makes types or members available by their simple names only 
within the compilation unit that actually contains the import declaration. The scope of the 
type(s) or member(s) introduced by an import declaration specifically does not include 
other compilation units in the same package, other import declarations in the current 
compilation unit, or a package declaration in the current compilation unit (except for the 
annotations of a package declaration). 


7.5.1 Single-Type-Import Declarations 


A single-type-import declaration imports a single type by giving its canonical 
name, making it available under a simple name in the module, class, and interface 
declarations of the compilation unit in which the single-type-import declaration 
appears. 


SingleTypelmportDeclaration: 
import TypeName ; 


The TypeName must be the canonical name of a class type, interface type, enum 
type, or annotation type (§6.7). 


The type must be either a member of a named package, or a member of a type 
whose outermost lexically enclosing type declaration (§8.1.3) is a member of a 
named package, or a compile-time error occurs. 


It is a compile-time error if the named type is not accessible ($6.6). 


If two single-type-import declarations in the same compilation unit attempt to 
import types with the same simple name, then a compile-time error occurs, unless 
the two types are the same type, in which case the duplicate declaration is ignored. 


If the type imported by the single-type-import declaration is declared in the 
compilation unit that contains the import declaration, the import declaration is 
ignored. 
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If a single-type-import declaration imports a type whose simple name is n, and the 
compilation unit also declares a top level type ($7.6) whose simple name is n, a 
compile-time error occurs. 


If a compilation unit contains both a single-type-import declaration that imports a 
type whose simple name is n, and a single-static-import declaration (§7.5.3) that 
imports a type whose simple name is n, a compile-time error occurs, unless the two 
types are the same type, in which case the duplicate declaration is ignored. 


Example 7.5.1-1. Single-Type-Import 


import java.util.Vector; 


causes the simple name Vector to be available within the class and interface declarations 
in a compilation unit. Thus, the simple name Vector refers to the type declaration Vector 
in the package java.util in all places where it is not shadowed (§6.4.1) or obscured 
(§6.4.2) by a declaration of a field, parameter, local variable, or nested type declaration 
with the same name. 


Note that the actual declaration of java.util.Vector is generic (§8.1.2). Once imported, 
the name Vector can be used without qualification in a parameterized type such as 
Vector<String>, or as the raw type Vector. A related limitation of the import 
declaration is that a nested type declared inside a generic type declaration can be imported, 
but its outer type is always erased. 


Example 7.5.1-2. Duplicate Type Declarations 
This program: 


import java.util.Vector; 
class Vector { Object[] vec; } 


causes a compile-time error because of the duplicate declaration of Vector, as does: 


import java.util.Vector; 
import myVector.Vector; 


where myVector is a package containing the compilation unit: 


package myVector; 
public class Vector { Object[] vec; } 


Example 7.5.1-3. No Import of a Subpackage 


Note that an import declaration cannot import a subpackage, only a type. 


For example, it does not work to try to import java.util and then use the name 
util.Random to refer to the type java. util.Random 
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import java.util; 
class Test { util.Random generator; } 
// incorrect: compile-time error 


Example 7.5.1-4. Importing a Type Name that is also a Package Name 


Package names and type names are usually different under the naming conventions 
described in §6.1. Nevertheless, in a contrived example where there is an unconventionally- 
named package Vector, which declares a public class whose name is Mosquito: 


package Vector; 
public class Mosquito { int capacity; } 


and then the compilation unit: 


package strange; 
import java.util.Vector; 
import Vector.Mosquito; 
class Test { 
public static void main(String[] args) { 
System.out.println(new Vector().getClass()); 
System.out.println(new Mosquito().getClass()); 


the single-type-import declaration importing class Vector from package java.util does 
not prevent the package name Vector from appearing and being correctly recognized in 
subsequent import declarations. The example compiles and produces the output: 


class java.util.Vector 
class Vector.Mosquito 


7.5.2 Type-Import-on-Demand Declarations 


A type-import-on-demand declaration allows all accessible types of a named 
package or type to be imported as needed. 


TypelmportOnDemanadDeclaration: 
import PackageOrTypeName . * ; 


The PackageOrTypeName must be the canonical name (§6.7) of a package, a class 
type, an interface type, an enum type, or an annotation type. 


If the PackageOrTypeName denotes a type (§6.5.4), then the type must be either 
a member of a named package, or a member of a type whose outermost lexically 
enclosing type declaration (§8.1.3) is a member of a named package, or a compile- 
time error occurs. 
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It is a compile-time error if the named package is not uniquely visible to the current 
module (§7.4.3), or if the named type is not accessible (§6.6). 


It is not a compile-time error to name either java. 1ang or the named package of the 
current compilation unit in a type-import-on-demand declaration. The type-import- 
on-demand declaration is ignored in such cases. 


Two or more type-import-on-demand declarations in the same compilation unit 
may name the same type or package. All but one of these declarations are 
considered redundant; the effect is as if that type was imported only once. 


If a compilation unit contains both a type-import-on-demand declaration and a 
static-import-on-demand declaration (§7.5.4) that name the same type, the effect is 
as if the static member types of that type (§8.5, $9.5) were imported only once. 


Example 7.5.2-1. Type-Import-on-Demand 


import java.util.*; 


causes the simple names of all public types declared in the package java.util to be 
available within the class and interface declarations of the compilation unit. Thus, the 
simple name Vector refers to the type Vector in the package java.util in all places 
in the compilation unit where that type declaration is not shadowed (§6.4.1) or obscured 


(§6.4.2). 


The declaration might be shadowed by a single-type-import declaration of a type whose 
simple name is Vector; by a type named Vector and declared in the package to which the 
compilation unit belongs; or any nested classes or interfaces. 


The declaration might be obscured by a declaration of a field, parameter, or local variable 
named Vector. 


(It would be unusual for any of these conditions to occur.) 


7.5.3 Single-Static-Import Declarations 


A single-static-import declaration imports all accessible static members with a 
given simple name from a type. This makes these st at ic members available under 
their simple name in the module, class, and interface declarations of the compilation 
unit in which the single-static-import declaration appears. 


SingleStaticImportDeclaration: 
import static TypeName . Identifier ; 


The TypeName must be the canonical name (§6.7) of a class type, interface type, 
enum type, or annotation type. 
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The type must be either a member of a named package, or a member of a type 
whose outermost lexically enclosing type declaration (§8.1.3) is a member of a 
named package, or a compile-time error occurs. 


It is a compile-time error if the named type is not accessible ($6.6). 


The Identifier must name at least one static member of the named type. It is a 
compile-time error if there is no stat ic member of that name, or if all of the named 
members are not accessible. 


It is permissible for one single-static-import declaration to import several fields or 
types with the same name, or several methods with the same name and signature. 
This occurs when the named type inherits multiple fields, member types, or 
methods, all with the same name, from its own supertypes. 


If two single-static-import declarations in the same compilation unit attempt to 
import types with the same simple name, then a compile-time error occurs, unless 
the two types are the same type, in which case the duplicate declaration is ignored. 


If a single-static-import declaration imports a type whose simple name is n, and 
the compilation unit also declares a top level type ($7.6) whose simple name is n, 
a compile-time error occurs. 


If a compilation unit contains both a single-static-import declaration that imports 
a type whose simple name is n, and a single-type-import declaration (§7.5.1) that 
imports a type whose simple name is n, a compile-time error occurs, unless the two 
types are the same type, in which case the duplicate declaration is ignored. 


7.5.4 Static-Import-on-Demand Declarations 


A static-import-on-demand declaration allows all accessible static members of 
a named type to be imported as needed. 


StaticImportOnDemandDeclaration: 
import static TypeName . * ; 


The TypeName must be the canonical name (§6.7) of a class type, interface type, 
enum type, or annotation type. 


The type must be either a member of a named package, or a member of a type 
whose outermost lexically enclosing type declaration (§8.1.3) is a member of a 
named package, or a compile-time error occurs. 


It is a compile-time error if the named type is not accessible ($6.6). 
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Two or more static-import-on-demand declarations in the same compilation unit 
may name the same type; the effect is as if there was exactly one such declaration. 


Two or more static-import-on-demand declarations in the same compilation unit 
may name the same member; the effect is as if the member was imported exactly 
once. 


It is permissible for one static-import-on-demand declaration to import several 
fields or types with the same name, or several methods with the same name and 
signature. This occurs when the named type inherits multiple fields, member types, 
or methods, all with the same name, from its own supertypes. 


If a compilation unit contains both a static-import-on-demand declaration and a 
type-import-on-demand declaration (§7.5.2) that name the same type, the effect is 
as if the static member types of that type (§8.5, $9.5) were imported only once. 


7.6 Top Level Type Declarations 


A top level type declaration declares a top level class type (§8 (Classes)) or a top 
level interface type (§9 Unterfaces)). 


TypeDeclaration: 
ClassDeclaration 
InterfaceDeclaration 
Extra ";" tokens appearing at the level of type declarations in a compilation unit have no 


effect on the meaning of the compilation unit. Stray semicolons are permitted in the Java 
programming language solely as a concession to C++ programmers who are used to placing 


";" after a class declaration. They should not be used in new Java code. 

In the absence of an access modifier, a top level type has package access: it is 
accessible only within ordinary compilation units of the package in which it is 
declared (§6.6.1). A type may be declared public to grant access to the type from 
code in other packages of the same module, and potentially from code in packages 
of other modules. 


It is a compile-time error if a top level type declaration contains any one of the 
following access modifiers: protected, private, Or static. 


It is a compile-time error if the name of a top level type appears as the name of any 
other top level class or interface type declared in the same package. 


PACKAGES AND MODULES Top Level Type Declarations 7.6 


The scope and shadowing of a top level type is specified in §6.3 and §6.4. 
The fully qualified name of a top level type is specified in §6.7. 
Example 7.6-1. Conflicting Top Level Type Declarations 


package test; 

import java.util.Vector; 

class Point { 
int yx ;> Ve 

} 

interface Point { // compile-time error #1 
int getR(); 
int getTheta(); 

} 


class Vector { Point[] pts; } // compile-time error #2 


Here, the first compile-time error is caused by the duplicate declaration of the name Point 
as both a class and an interface in the same package. A second compile-time error is the 
attempt to declare the name Vector both by a class type declaration and by a single-type- 
import declaration. 


Note, however, that it is not an error for the name of a class to also name a type that otherwise 
might be imported by a type-import-on-demand declaration (§7.5.2) in the compilation unit 
($7.3) containing the class declaration. Thus, in this program: 


package test; 
import java.util.*; 
class Vector {} // not a compile-time error 


the declaration of the class Vector is permitted even though there is also a class 
java.util.Vector. Within this compilation unit, the simple name Vector refers to the 
class test .Vector, not to java.util.Vector (which can still be referred to by code 
within the compilation unit, but only by its fully qualified name). 


Example 7.6-2. Scope of Top Level Types 


package points; 
class Point { 


Sn Sy ye // coordinates 
PointColor color; // color of this point 
Point next; // next point with this color 


static int nPoints; 

} 

class PointColor { 
Point first; // first point with this color 
PointColor(int color) { this.color = color; } 
private int color; // color components 


This program defines two classes that use each other in the declarations of their class 
members. Because the class types Point and PointColor have all the type declarations 
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in package points, including all those in the current compilation unit, as their scope, this 
program compiles correctly. That is, forward reference is not a problem. 


Example 7.6-3. Fully Qualified Names 


class Point { int x, y; } 


In this code, the class Point is declared in a compilation unit with no package declaration, 
and thus Point is its fully qualified name, whereas in the code: 


package vista; 
class Point { int x, y; } 


the fully qualified name of the class Point is vista.Point. (The package name vista 
is suitable for local or personal use; if the package were intended to be widely distributed, 
it would be better to give it a unique package name (§6.1).) 


An implementation of the Java SE Platform must keep track of types within 
packages by the combination of their enclosing module names and their binary 
names (§13.1). Multiple ways of naming a type must be expanded to binary names 
to make sure that such names are understood as referring to the same type. 


For example, if a compilation unit contains the single-type-import declaration (§7.5.1): 
import java.util.Vector; 


then within that compilation unit, the simple name Vector and the fully qualified name 
java.util.Vector refer to the same type. 


If and only if packages are stored in a file system (§7.2), the host system may 
choose to enforce the restriction that it is a compile-time error if a type is not found 
in a file under a name composed of the type name plus an extension (suchas . java 
or . jav) if either of the following is true: 


¢ The type is referred to by code in other ordinary compilation units of the package 
in which the type is declared. 


¢ The type is declared public (and therefore is potentially accessible from code 
in other packages). 


This restriction implies that there must be at most one such type per compilation unit. 
This restriction makes it easy for a Java compiler to find a named class within a package. 
In practice, many programmers choose to put each class or interface type in its own 
compilation unit, whether or not it is public or is referred to by code in other compilation 
units. 
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For example, the source code for a public type wet .sprocket.Toad would be found 
in a file Toad. java in the directory wet /sprocket, and the corresponding object code 
would be found in the file Toad. class in the same directory. 


7.7 Module Declarations 


A module declaration specifies a new named module. A named module specifies 
dependences on other modules to define the universe of classes and interfaces 
available to its own code; and specifies which of its packages are exported or 
opened in order to populate the universe of classes and interfaces available to other 
modules which specify a dependence on it. 


A "dependence" is what is expressed by a requires directive, independent of whether a 
module exists with the name specified by the directive. A "dependency" is the observable 
module enumerated by resolution (as described in the java.lang.module package 
specification) for a given requires directive. Generally, the rules of the Java programming 
language are more interested in dependences than dependencies. 


ModuleDeclaration: 
{Annotation} [open] module Identifier { . Identifier} 
{ {ModuleDirective} } 


A module declaration introduces a module name that can be used in other module 
declarations to express relationships between modules. A module name consists of 


one or more Java identifiers ($3.8) separated by "." tokens. 


There are two kinds of modules: normal modules and open modules. The kind of 
a module determines the nature of access to the module's types, and the members 
of those types, for code outside the module. 


A normal module, without the open modifier, grants access at compile time and 
run time to types in only those packages which are explicitly exported. 


An open module, with the open modifier, grants access at compile time to types in 
only those packages which are explicitly exported, but grants access at run time to 
types in all its packages, as if all packages had been exported. 


For code outside a module (whether the module is normal or open), the access 
granted at compile time or run time to types in the module's exported packages is 
specifically to the public and protected types in those packages, and the public 
and protected members of those types ($6.6). No access is granted at compile time 
or run time to types, or their members, in packages which are not exported. Code 
inside the module may access public and protected types, and the public and 
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protected members of those types, in all packages in the module at both compile 
time and run time. 


Distinct from access at compile time and access at run time, the Java SE Platform 
provides reflective access via the Core Reflection API (§1.4). A normal module 
grants reflective access to types in only those packages which are explicitly 
exported or explicitly opened (or both). An open module grants reflective access 
to types in all its packages, as if all packages had been opened. 


For code outside a normal module, the reflective access granted to types in the 
module's exported (and not opened) packages is specifically to the public and 
protected types in those packages, and the public and protected members of 
those types. The reflective access granted to types in the module's opened packages 
(whether exported or not) is to all types in those packages, and all members of those 
types. No reflective access is granted to types, or their members, in packages which 
are not exported or opened. Code inside the module enjoys reflective access to all 
types, and all their members, in all packages in the module. 


For code outside an open module, the reflective access granted to types in the 
module's opened packages (that is, all packages in the module) is to all types in 
those packages, and all members of those types. Code inside the module enjoys 
reflective access to all types, and all their members, in all packages in the module. 


The directives of a module declaration specify the module's dependences on other 
modules (via requires, $7.7.1), the packages it makes available to other modules 
(via exports and opens, §7.7.2), the services it consumes (via uses, §7.7.3), and 
the services it provides (via provides, §7.7.4). 


ModuleDirective: 
requires {RequiresModifier} ModuleName ; 
exports PackageName [to ModuleName {, ModuleName}] ; 
opens PackageName [to ModuleName {, ModuleName}] ; 
uses TypeName ; 
provides TypeName with TypeName {, TypeName} ; 


RequiresModifier: 
(one of) 


transitive static 


If and only if packages are stored in a file system (§7.2), the host system may choose 
to enforce the restriction that it is a compile-time error if a module declaration is 
not found in a file under a name composed of module-info plus an extension (such 
aS .javaor. jav). 
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To aid comprehension, it is customary, though not required, for a module declaration to 
group its directives, so that the requires directives which pertain to modules are visually 
distinct from the exports and opens directives which pertain to packages, and from the 
uses and provides directives which pertain to services. For example: 


module com.example.foo { 
requires com.example.foo.http; 
requires java.logging; 


requires transitive com.example.foo.network; 


exports com.example.foo.bar; 
exports com.example.foo.internal to com.example.foo.probe; 


opens com.example.foo.quux; 
opens com.example.foo.internal to com.example.foo.network, 
com.example.foo.probe; 


uses com.example.foo.spi.Intf; 
provides com.example.foo.spi.Intf with com.example.foo.Impl; 


The opens directives can be avoided if the module is open: 


open module com.example.foo { 
requires com.example.foo.http; 
requires java.logging; 


requires transitive com.example.foo.network; 


exports com.example.foo.bar; 
exports com.example.foo.internal to com.example.foo.probe; 


uses com.example.foo.spi.Intf; 
provides com.example.foo.spi.Intf with com.example.foo.Impl; 


Development tools for the Java programming language are encouraged to highlight 
requires transitive directives and unqualified exports directives, as these form the 
primary API of a module. 


7.7.1 Dependences 


The requires directive specifies the name of a module on which the current 
module has a dependence. 


A requires directive must not appear in the declaration of the java.base module, 
or a compile-time error occurs, because it is the primordial module and has no 
dependences (§8.1.4). 
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If the declaration of a module does not express a dependence on the java.base 
module, and the module is not itself java.base, then the module has an implicitly 
declared dependence on the java.base module. 


The requires keyword may be followed by the modifier transitive. This causes 
any module which requires the current module to have an implicitly declared 
dependence on the module specified by the requires transitive directive. 


The requires keyword may be followed by the modifier static. This specifies 
that the dependence, while mandatory at compile time, is optional at run time. 


If the declaration of a module expresses a dependence on the java.base module, 
and the module is not itself java.base, then it is a compile-time error if a modifier 
appears after the requires keyword. 


It is a compile-time error if more than one requires directive in a module 
declaration specifies the same module name. 


It is a compile-time error if resolution, as described in the java.lang.module 
package specification, with the current module as the only root module, fails for 
any of the reasons described in the java. 1ang.module package specification. 


For example, if a requires directive specifies a module that is not observable, or if the 
current module directly or indirectly expresses a dependence on itself. 


If resolution succeeds, then its result specifies the modules that are read by the 
current module. The modules read by the current module determine which ordinary 
compilation units are visible to the current module (§7.3). The types declared in 
those ordinary compilation units (and only those ordinary compilation units) may 
be accessible to code in the current module (§6.6). 


The Java SE Platform distinguishes between named modules that are explicitly declared 
(that is, with a module declaration) and named modules that are implicitly declared (that 
is, automatic modules). However, the Java programming language does not surface the 
distinction: requires directives refer to named modules without regard for whether they 
are explicitly declared or implicitly declared. 


While automatic modules are convenient for migration, they are unreliable in the sense 
that their names and exported packages may change when their authors convert them 
to explicitly declared modules. A Java compiler is encouraged to issue a warning if 
a requires directive refers to an automatic module. An especially strong warning is 
recommended if the transitive modifier appears in the directive. 


Example 7.1.1-1. Resolution of requires transitive directives 


Suppose there are four module declarations as follows: 


PACKAGES AND MODULES Module Declarations 7.7 


module m.A { 
requires m.B; 


module m.B { 
requires transitive m.C; 


module m.C { 
requires transitive m.D; 


module m.D { 
exports p; 


where the package p exported by m.D is declared as follows: 


package p; 
public class Point {} 


and where a package client in module m.A refers to the public type Point in the 
exported package p: 


package client; 
import p.Point; 
public class Test { 
public static void main(String[] args) { 
System.out.println(new Point ()); 


The modules may be compiled as follows, assuming that the current directory has one 
subdirectory per module, named after the module it contains: 


javac —-module-source-path . -d . -—-module m.D 
javac —-module-source-path . -d . —-module m.C 
javac —-module-source-path . -d . -—-module m.B 
javac —-module-source-path . -d . —-module m.A 


The program client .Test may be run as follows: 
java --module-path . --module m.A/client.Test 


The reference from code in m.A to the exported public type Point inm.D is legal because 
m.Areads m.D, and m.D exports the package containing Point. Resolution determines that 
m.A reads m.D as follows: 


* m.A requires m.B and therefore reads m.B. 
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e Since m.Areads m.B, and since m.B requires transitivem.c, resolution determines 
that m.A reads m.c. 


¢ Then, since m.A reads m.c, and since m.c requires transitive m.D, resolution 
determines that m.A reads m.D. 


In effect, a module may read another module through multiple levels of dependence, in 
order to support arbitrary amounts of refactoring. Once a module is released for someone 
to reuse (via requires), the module's author has committed to its name and API but is free 
to refactor its content into other modules which the original module reuses (via requires 
transitive) for the benefit of consumers. In the example above, package p may have 
been exported originally by m.B (thus, m. A requires m..B) but refactoring has caused some 
of m.B's content to move into m.c and m.D. By using a chain of requires transitive 
directives, the family of m.B, m.c, and m.D can preserve access to package p for code in 
m.A without forcing any changes to the requires directives of m.A. Note that package p 
in m.D is not "re-exported" by m.c and m.B; rather, m.A is made to read m.D directly. 


7.7.2 Exported and Opened Packages 


The exports directive specifies the name of a package to be exported by the current 
module. For code in other modules, this grants access at compile time and run time 
to the public and protected types in the package, and the public and protected 
members of those types (§6.6). It also grants reflective access to those types and 
members for code in other modules. 


The opens directive specifies the name of a package to be opened by the current 
module. For code in other modules, this grants access at run time, but not compile 
time, to the public and protected types in the package, and the public and 
protected members of those types. It also grants reflective access to all types in 
the package, and all their members, for code in other modules. 


It is a compile-time error if the package specified by exports is not declared by a 
compilation unit associated with the current module (§7.3). 


Itis permitted for opens to specify a package which is not declared by a compilation 
unit associated with the current module. (If the package should happen to be 
declared by an observable compilation unit associated with another module, the 
opens directive has no effect on that other module.) 


It is a compile-time error if more than one exports directive in a module 
declaration specifies the same package name. 


It is a compile-time error if more than one opens directive in a module declaration 
specifies the same package name. 


It is a compile-time error if an opens directive appears in the declaration of an open 
module. 
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If an exports or opens directive has a to clause, then the directive is qualified; 
otherwise, it is unqualified. For a qualified directive, the public and protected 
types in the package, and their public and protected members, are accessible 
solely to code in the modules specified in the to clause. The modules specified in 
the to clause are referred to as friends of the current module. For an unqualified 
directive, these types and their members are accessible to code in any module. 


It is permitted for the to clause of an exports Or opens directive to specify a 
module which is not observable (§7.7.6). 


It is a compile-time error if the to clause of a given exports directive specifies the 
same module name more than once. 


It is a compile-time error if the to clause of a given opens directive specifies the 
same module name more than once. 


7.7.3 Service Consumption 


The uses directive specifies a service for which the current module may discover 
providers via java.util.ServiceLoader. 


The service must be a class type, an interface type, or an annotation type. It is a 
compile-time error if a uses directive specifies an enum type (§8.9) as the service. 


The service may be declared in the current module or in another module. If the 
service is not declared in the current module, then the service must be accessible 
to code in the current module (§6.6), or a compile-time error occurs. 


It is a compile-time error if more than one uses directive in a module declaration 
specifies the same service. 


7.7.4 Service Provision 


The provides directive specifies a service for which the with clause specifies one 
or more service providers to java.util.ServiceLoader. 


The service must be a class type, an interface type, or an annotation type. It is a 
compile-time error if a provides directive specifies an enum type (§8.9) as the 
service. 


The service may be declared in the current module or in another module. If the 
service is not declared in the current module, then the service must be accessible 
to code in the current module (§6.6), or a compile-time error occurs. 
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Every service provider must be a class type or an interface type, that is public, and 
that is top level or nested static, or a compile-time error occurs. 


Every service provider must be declared in the current module, or a compile-time 
error occurs. 


If a service provider explicitly declares a public constructor with no formal 
parameters, or implicitly declares a public default constructor (§8.8.9), then that 
constructor is called the provider constructor. 


If a service provider explicitly declares a public static method called provider 
with no formal parameters, then that method is called the provider method. 


If a service provider has a provider method, then its return type must (i) either be 
declared in the current module, or be declared in another module and be accessible 
to code in the current module; and (ii) be a subtype of the service specified in the 
provides directive; or a compile-time error occurs. 


While a service provider that is specified by a provides directive must be declared in 
the current module, its provider method may have a return type that is declared in another 
module. Also, note that when a service provider declares a provider method, the service 
provider itself need not be a subtype of the service. 


If a service provider does not have a provider method, then that service provider 
must have a provider constructor and must be a subtype of the service specified in 
the provides directive, or a compile-time error occurs. 


It is a compile-time error if more than one provides directive in a module 
declaration specifies the same service. 


It is a compile-time error if the with clause of a given provides directive specifies 
the same service provider more than once. 


7.7.5 Unnamed Modules 


An observable ordinary compilation unit that the host system does not associate 
with a named module (§7.3) is associated with an unnamed module. 


Unnamed modules are provided by the Java SE Platform in recognition of the fact 
that programs developed prior to Java SE 9 could not declare named modules. 
In addition, the reasons for the Java SE Platform providing unnamed packages 
($7.4.2) are largely applicable to unnamed modules. 


An implementation of the Java SE Platform must support at least one unnamed 
module. An implementation may support more than one unnamed module, but is 
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not required to do so. Which ordinary compilation units are associated with each 
unnamed module is determined by the host system. 


The host system may associate ordinary compilation units in a named package with 
an unnamed module. 


The rules for unnamed modules are designed to maximize their interoperation with 
named modules, as follows: 


e« An unnamed module reads every observable module (§7.7.6). 


By virtue of the fact that an ordinary compilation unit associated with an unnamed 
module is observable, the associated unnamed module is observable. Thus, if the 
implementation of the Java SE Platform supports more than one unnamed module, every 
unnamed module is observable; and each unnamed module reads every unnamed module 
including itself. 


However, it is important to realize that the ordinary compilation units of an unnamed 
module are never visible to a named module (§7.3) because no requires directive can 
arrange for a named module to read an unnamed module. The Core Reflection API of 
the Java SE Platform may be used to arrange for a named module to read an unnamed 
module at run time. 


e« An unnamed module exports every package whose ordinary compilation units 
are associated with that unnamed module. 


¢ An unnamed module opens every package whose ordinary compilation units are 
associated with that unnamed module. 


7.7.6 Observability of a Module 


A module is observable if at least one of the following is true: 


¢ A modular compilation unit containing the declaration of the module is 
observable (§7.3). 


¢ An ordinary compilation unit associated with the module is observable. 
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Classes 


Crass declarations define new reference types and describe how they are 
implemented (§8.1). 


A top level class is a class that is not a nested class. 


A nested class is any class whose declaration occurs within the body of another 
class or interface. 


This chapter discusses the common semantics of all classes - top level (§7.6) 
and nested (including member classes (§8.5, §9.5), local classes (§14.3) and 
anonymous classes (§15.9.5)). Details that are specific to particular kinds of classes 
are discussed in the sections dedicated to these constructs. 


A named class may be declared abst ract (§8.1.1.1) and must be declared abstract 
if it is incompletely implemented; such a class cannot be instantiated, but can be 
extended by subclasses. A class may be declared final ($8.1.1.2), in which case it 
cannot have subclasses. If a class is declared public, then it can be referred to from 
code in any package of its module and potentially from code in other modules. Each 
class except Object is an extension of (that is, a subclass of) a single existing class 
(§8.1.4) and may implement interfaces (§8.1.5). Classes may be generic (§8.1.2), 
that is, they may declare type variables whose bindings may differ among different 
instances of the class. 


Classes may be decorated with annotations (§9.7) just like any other kind of 
declaration. 


The body of a class declares members (fields and methods and nested classes 
and interfaces), instance and static initializers, and constructors (§8.1.6). The 
scope (§6.3) of a member (§8.2) is the entire body of the declaration of the class 
to which the member belongs. Field, method, member class, member interface, 
and constructor declarations may include the access modifiers (§6.6) public, 
protected, Of private. The members of a class include both declared and 
inherited members (§8.2). Newly declared fields can hide fields declared in a 
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superclass or superinterface. Newly declared class members and interface members 
can hide class or interface members declared in a superclass or superinterface. 
Newly declared methods can hide, implement, or override methods declared in a 
superclass or superinterface. 


Field declarations ($8.3) describe class variables, which are incarnated once, and 
instance variables, which are freshly incarnated for each instance of the class. A 
field may be declared final (§8.3.1.2), in which case it can be assigned to only 
once. Any field declaration may include an initializer. 


Member class declarations (§8.5) describe nested classes that are members of the 
surrounding class. Member classes may be static, in which case they have no 
access to the instance variables of the surrounding class; or they may be inner 
classes (§8.1.3). 


Member interface declarations ($8.5) describe nested interfaces that are members 
of the surrounding class. 


Method declarations (§8.4) describe code that may be invoked by method 
invocation expressions ($15.12). A class method is invoked relative to the class 
type; an instance method is invoked with respect to some particular object that is 
an instance of a class type. A method whose declaration does not indicate how 
it is implemented must be declared abstract. A method may be declared final 
(§8.4.3.3), in which case it cannot be hidden or overridden. A method may be 
implemented by platform-dependent native code (§8.4.3.4). A synchronized 
method (§8.4.3.6) automatically locks an object before executing its body and 
automatically unlocks the object on return, as if by use of a synchronized 
statement ($14.19), thus allowing its activities to be synchronized with those of 
other threads ($17 (Threads and Locks)). 


Method names may be overloaded (§8.4.9). 


Instance initializers ($8.6) are blocks of executable code that may be used to help 
initialize an instance when it is created (§15.9). 


Static initializers ($8.7) are blocks of executable code that may be used to help 
initialize a class. 


Constructors ($8.8) are similar to methods, but cannot be invoked directly by a 
method call; they are used to initialize new class instances. Like methods, they may 
be overloaded (§8.8.8). 
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8.1 Class Declarations 


A class declaration specifies a new named reference type. 


There are two kinds of class declarations: normal class declarations and enum 
declarations. 


ClassDeclaration: 
NormalClassDeclaration 
EnumDeclaration 


NormalClassDeclaration: 
{ClassModifier} class Typeldentifier [TypeParameters] 
[Superclass] [Superinterfaces] ClassBody 


The rules in this section apply to all class declarations, including enum declarations. 
However, special rules apply to enum declarations with regard to class modifiers, 
inner classes, and superclasses; these rules are stated in §8.9. 


The 7ypeldentifier in a class declaration specifies the name of the class. 


It is a compile-time error if a class has the same simple name as any of its enclosing 
classes or interfaces. 


The scope and shadowing of a class declaration is specified in §6.3 and $6.4. 


8.1.1 Class Modifiers 


A class declaration may include class modifiers. 


ClassModifier: 
(one of) 


Annotation public protected private 


abstract static final strictfp 


The rules for annotation modifiers on a class declaration are specified in §9.7.4 
and §9.7.5. 


The access modifier public (§6.6) pertains only to top level classes (§7.6) and 
member classes (§8.5), not to local classes ($14.3) or anonymous classes (§15.9.5). 


The access modifiers protected and private pertain only to member classes 
within a directly enclosing class declaration (§8.5). 
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The modifier static pertains only to member classes (§8.5.1), not to top level or 
local or anonymous classes. 


It is a compile-time error if the same keyword appears more than once as a modifier 
for a class declaration, or if a class declaration has more than one of the access 
modifiers public, protected, and private ($6.6). 


If two or more (distinct) class modifiers appear in a class declaration, then it is customary, 
though not required, that they appear in the order consistent with that shown above in the 
production for ClassModifier. 


8.1.1.1 abstract Classes 
An abstract Class is a class that is incomplete, or to be considered incomplete. 


It is acompile-time error if an attempt is made to create an instance of an abstract 
class using a class instance creation expression (§15.9.1). 


A subclass of an abstract class that is not itself abstract may be instantiated, 
resulting in the execution of a constructor for the abstract class and, therefore, 
the execution of the field initializers for instance variables of that class. 


A normal class may have abst ract methods, that is, methods that are declared but 
not yet implemented (§8.4.3.1), only if it is an abstract class. It is a compile-time 
error if a normal class that is not abstract has an abstract method. 


A class chas abstract methods if either of the following is true: 


e« Any of the member methods (§8.2) of c - either declared or inherited - is 


abstract. 


¢ Any of c's superclasses has an abstract method declared with package access, 
and there exists no method that overrides the abstract method from c or from 
a superclass of c. 


It is a compile-time error to declare an abstract class type such that it is not 
possible to create a subclass that implements all of its abstract methods. This 
situation can occur if the class would have as members two abstract methods 
that have the same method signature (§8.4.2) but return types for which no type is 
return-type-substitutable with both (§8.4.5). 


Example 8.1.1.1-1. Abstract Class Declaration 


abstract class Point { 
inte x =) dy. yee 1; 
void move(int dx, int dy) { 
x += dx; 
y += dy; 


CLASSES Class Declarations 8.1 


alert (); 
} 
abstract void alert(); 
} 
abstract class ColoredPoint extends Point { 
int color; 
} 
class SimplePoint extends Point { 
void alert() { } 


Here, a class Point is declared that must be declared abstract, because it contains 
a declaration of an abstract method named alert. The subclass of Point named 
ColoredPoint inherits the abstract method alert, so it must also be declared 
abstract. On the other hand, the subclass of Point named SimplePoint provides an 
implementation of alert, so it need not be abstract. 


The statement: 
Point p = new Point(); 


would result in a compile-time error; the class Point cannot be instantiated because it is 
abstract. However, a Point variable could correctly be initialized with a reference to 
any subclass of Point, and the class SimplePoint is not abstract, so the statement: 


Point p = new SimplePoint (); 


would be correct. Instantiation of a SimplePoint causes the default constructor and field 
initializers for x and y of Point to be executed. 


Example 8.1.1.1-2. Abstract Class Declaration that Prohibits Subclasses 


interface Colorable { 
void setColor(int color); 

} 

abstract class Colored implements Colorable { 
public abstract int setColor(int color); 


These declarations result in a compile-time error: it would be impossible for any subclass 
of class Colored to provide an implementation of a method named set Color, taking one 
argument of type int, that can satisfy both abstract method specifications, because the one 
in interface Colorable requires the same method to return no value, while the one in class 
Colored requires the same method to return a value of type int (§8.4). 


Aclass type should be declared abst ract only if the intent is that subclasses can be created 
to complete the implementation. If the intent is simply to prevent instantiation of a class, 
the proper way to express this is to declare a constructor (§8.8.10) of no arguments, make 
it private, never invoke it, and declare no other constructors. A class of this form usually 
contains class methods and variables. 
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The class Math is an example of a class that cannot be instantiated; its declaration looks 
like this: 


public final class Math { 
private Math() { } // never instantiate this class 
. declarations of class variables and methods . 


8.1.1.2 final Classes 


A class can be declared final if its definition is complete and no subclasses are 
desired or required. 


It is a compile-time error if the name of a final class appears in the extends clause 
(§8.1.4) of another class declaration; this implies that a final class cannot have 
any subclasses. 


It is a compile-time error if a class is declared both final and abstract, because 
the implementation of such a class could never be completed (§8.1.1.1). 


Because a final class never has any subclasses, the methods of a final class are 
never overridden (§8.4.8.1). 


8.1.1.3 strictfp Classes 


The effect of the strictfp modifier is to make all float or double expressions 
within the class declaration (including within variable initializers, instance 
initializers, static initializers, and constructors) be explicitly FP-strict ($15.4). 


This implies that all methods declared in the class, and all nested types declared in 
the class, are implicitly strict £p. 


8.1.2 Generic Classes and Type Parameters 


A class is generic if it declares one or more type variables ($4.4). 


These type variables are known as the type parameters of the class. The type 
parameter section follows the class name and is delimited by angle brackets. 


TypeParameters: 
< TypeParameterList > 


TypeParameterList: 
TypeParameter {, TypeParameter} 


The following productions from §4.4 are shown here for convenience: 
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TypeParameter: 
{TypeParameterModifier} Typeldentifier [TypeBound] 


TypeParameterModifier: 
Annotation 


TypeBound: 
extends TypeVariable 
extends ClassOrInterfaceType {AdditionalBound} 


AdditionalBound: 
& InterfaceType 


The rules for annotation modifiers on a type parameter declaration are specified 
in §9.7.4 and 89.7.5. 


In a class's type parameter section, a type variable r directly depends on a type 
variable s if sis the bound of r, while r depends on s if either rT directly depends on 
sor T directly depends on a type variable uv that depends on s (using this definition 
recursively). It is a compile-time error if a type variable in a class's type parameter 
section depends on itself. 


The scope and shadowing of a class's type parameter is specified in $6.3 and §6.4. 


A generic class declaration defines a set of parameterized types (§4.5), one for each 
possible parameterization of the type parameter section by type arguments. All of 
these parameterized types share the same class at run time. 


For instance, executing the code: 
Vector<String> x = new Vector<String>(); 
Vector<Integer> y = new Vector<Integer>(); 


boolean b = x.getClass() == y.getClass(); 


will result in the variable b holding the value t rue. 


It is a compile-time error if a generic class is a direct or indirect subclass of 
Throwable (§11.1.1). 


This restriction is needed since the catch mechanism of the Java Virtual Machine works 
only with non-generic classes. 


It is a compile-time error to refer to a type parameter of a generic class c in any 
of the following: 
¢ the declaration of a static member of c (§8.3.1.1, §8.4.3.2, §8.5.1). 


¢ the declaration of a static member of any type declaration nested within c. 
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¢ a static initializer of c (§8.7), or 


* a Static initializer of any class declaration nested within c. 


Example 8.1.2-1. Mutually Recursive Type Variable Bounds 


interface ConvertibleTo<T> { 
T convert (); 
} 
class ReprChange<T extends ConvertibleTo<S>, 
S extends ConvertibleTo<T>> { 


Ts tes 
void set(S s) { t = s.convert(); } 
S get () { return t.convert(); } 


Example 8.1.2-2. Nested Generic Classes 


class Seq<T> { 
T head; 
Seq<T> tail; 


Seq() { this(null, null); } 

Seq(T head, Seq<T> tail) { 
this.head = head; 
this.tail = tail; 

} 


boolean isEmpty() { return tail == null; } 


class Zipper<S> { 
Seq<Pair<T,S>> zip(Seq<S> that) { 


if (isEmpty() || that.isEmpty()) { 
return new Seq<Pair<T,S>>(); 
+ @1se@ { 


Seq<T>.Zipper<S> tailZipper = 
tail.new Zipper<S>(); 

return new Seq<Pair<T,S>> ( 
new Pair<T,S>(head, that.head), 
tailZipper.zip(that.tail)); 


} 
class Pair<T, S> { 

T fst; S snd; 

Pair(T f, S s) { fst = f; snd = s; } 
} 
class Test { 

public static void main(String[] args) { 

Seq<String> strs = 
new Seq<String> ( 


CLASSES 


CLASSES Class Declarations 


wa", 
new Seq<String>("b", 
new Seq<String>())); 
Seq<Number> nums = 
new Seq<Number> ( 
new Integer(1), 
new Seq<Number>(new Double(1.5), 
new Seq<Number>())); 


Seq<String>.Zipper<Number> zipper = 
strs.new Zipper<Number>(); 


Seq<Pair<String,Number>> combined 
zipper.zip(nums) ; 


8.1.3. Inner Classes and Enclosing Instances 


An inner class is a nested class that is not explicitly or implicitly declared static. 


An inner class may be a non-st atic member class (§8.5), a local class ($14.3), or 
an anonymous class (§15.9.5). A member class of an interface is implicitly static 
(§9.5) so is never considered to be an inner class. 


It is a compile-time error if an inner class declares a static initializer (§8.7). 


It is a compile-time error if an inner class declares a member that is explicitly or 
implicitly static, unless the member is a constant variable (§4.12.4). 


An inner class may inherit static members that are not constant variables even 
though it cannot declare them. 


A nested class that is not an inner class may declare static members freely, in 
accordance with the usual rules of the Java programming language. 


Example 8.1.3-1. Inner Class Declarations and Static Members 


class HasStatic { 
static int j = 100; 
} 
class Outer { 
class Inner extends HasStatic { 
static final int x = 3; // OK: constant variable 
static int y = 4; // Compile-time error: an inner class 
} 
static class NestedButNotInner{ 
Static int: 2 = 5; // OK: not an inner class 
} 


interface NeverInner {} // Interfaces are never inner 
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A statement or expression occurs in a static context if and only if the innermost 
method, constructor, instance initializer, static initializer, field initializer, or 
explicit constructor invocation statement enclosing the statement or expression is 
a static method, a static initializer, the variable initializer of a static variable, or an 
explicit constructor invocation statement (§8.8.7.1). 


Aninner class cis a direct inner class of a class or interface oif ois the immediately 
enclosing type declaration of c and the declaration of c does not occur in a static 
context. 


A class cis an inner class of class or interface o if it is either a direct inner class 
of oor an inner class of an inner class of o. 


It is unusual, but possible, for the immediately enclosing type declaration of an inner class 
to be an interface. This only occurs if the class is declared in a default method body (§9.4). 
Specifically, it occurs if an anonymous or local class is declared in a default method body, 
or a member class is declared in the body of an anonymous class that is declared in a default 
method body. 


A class or interface ois the zeroth lexically enclosing type declaration of itself. 


A class o is the n'th lexically enclosing type declaration of a class c if it is 
the immediately enclosing type declaration of the n-/'th lexically enclosing type 
declaration of c. 


An instance i of a direct inner class c of a class or interface o is associated with an 
instance of o, known as the immediately enclosing instance of i. The immediately 
enclosing instance of an object, if any, is determined when the object is created 
(§15.9.2). 


An object o is the zeroth lexically enclosing instance of itself. 


An object o is the n'th lexically enclosing instance of an instance i if it is the 
immediately enclosing instance of the n-/'th lexically enclosing instance of i. 


An instance of an inner class z whose declaration occurs in a static context has 
no lexically enclosing instances. However, if r is immediately declared within a 
static method or static initializer then z does have an enclosing block, which is the 
innermost block statement lexically enclosing the declaration of r. 


For every superclass s of c which is itself a direct inner class of a class or interface 
So, there is an instance of so associated with i, known as the immediately enclosing 
instance of i with respect to s. The immediately enclosing instance of an object 
with respect to its class' direct superclass, if any, is determined when the superclass 
constructor is invoked via an explicit constructor invocation statement (§8.8.7.1). 
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When an inner class (whose declaration does not occur in a static context) refers to 
an instance variable that is a member of a lexically enclosing type declaration, the 
variable of the corresponding lexically enclosing instance is used. 


Any local variable, formal parameter, or exception parameter used but not declared 
in an inner class must either be declared final or be effectively final (§4.12.4), or 
a compile-time error occurs where the use is attempted. 


Any local variable used but not declared in an inner class must be definitely 
assigned (§16 (Definite Assignment)) before the body of the inner class, or a 
compile-time error occurs. 


Similar rules on variable use apply in the body of a lambda expression (§15.27.2). 


A blank final field (§4.12.4) of a lexically enclosing type declaration may not be 
assigned within an inner class, or a compile-time error occurs. 


Example 8.1.3-2. Inner Class Declarations 


class Outer { 
int i = 100; 
static void classMethod() { 
final int 1 = 200; 
class LocalInStaticContext { 
int k = i; // Compile-time error 
int m= 1; // OK 


} 
void foo() { 
class Local { // A local class 
int j = i; 


The declaration of class LocalInStaticContext occurs in a static context due to being 
within the static method classMethod. Instance variables of class Outer are not available 
within the body of a static method. In particular, instance variables of Outer are not 
available inside the body of LocalInStaticContext. However, local variables from the 
surrounding method may be referred to without error (provided they are declared final 
or are effectively final). 


Inner classes whose declarations do not occur in a static context may freely refer to the 
instance variables of their enclosing type declaration. An instance variable is always defined 
with respect to an instance. In the case of instance variables of an enclosing type declaration, 
the instance variable must be defined with respect to an enclosing instance of that declared 
type. For example, the class Local above has an enclosing instance of class Outer. As a 
further example: 


class WithDeepNesting { 
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boolean toBe; 
WithDeepNesting(boolean b) { toBe = b; } 


class Nested { 
boolean theQuestion; 
class DeeplyNested { 
DeeplyNested() { 
theQuestion = toBe || !toBe; 
} 


Here, every instance of WithDeepNesting.Nested.DeeplyNested has an enclosing 
instance of class WithDeepNest ing.Nested (its immediately enclosing instance) and an 
enclosing instance of class WithDeepNesting (its 2nd lexically enclosing instance). 


8.1.4 Superclasses and Subclasses 


The optional extends clause in a normal class declaration specifies the direct 
superclass of the current class. 


Superclass: 
extends ClassType 


The extends clause must not appear in the definition of the class object, or a 
compile-time error occurs, because it is the primordial class and has no direct 
superclass. 


The ClassType must name an accessible class type ($6.6), or a compile-time error 
occurs. 


It is a compile-time error if the ClassType names a class that is final, because 
final classes are not allowed to have subclasses (§8.1.1.2). 


It is a compile-time error if the ClassType names the class Enum or any invocation 
of Enum (§8.9). 


If the ClassType has type arguments, it must denote a well-formed parameterized 
type ($4.5), and none of the type arguments may be wildcard type arguments, or 
a compile-time error occurs. 


Given a (possibly generic) class declaration c<Fy,...,F,> (n = 0, Cc # Object), the 
direct superclass of the class type C<Fj,...,F;> is the type given in the extends 
clause of the declaration of cif an extends clause is present, or Object otherwise. 


Given a generic class declaration c<F),...,F,> (n > 0), the direct superclass of the 
parameterized class type C<Tj,...,T,>, where T; (1 <i <n) is a type, is D<U; 9,...,Ux 
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@>, where D<Uj,...,U;,> 1s the direct superclass of c<Fj,...,F,> and 9 is the substitution 
[Fi:=Ty,-.+,Fni=Tn]. 


A class is said to be a direct subclass of its direct superclass. The direct superclass 
is the class from whose implementation the implementation of the current class is 
derived. 


The subclass relationship is the transitive closure of the direct subclass relationship. 
A class a is a subclass of class c if either of the following is true: 


¢ ais the direct subclass of c 


¢ There exists a class B such that a is a subclass of 3B, and B is a subclass of c, 
applying this definition recursively. 


Class cis said to be a superclass of class a whenever aA is a subclass of c. 


Example 8.1.4-1. Direct Superclasses and Subclasses 


class Point { int x, y; } 
final class ColoredPoint extends Point { int color; } 
class Colored3DPoint extends ColoredPoint { int z; } // error 


Here, the relationships are as follows: 


¢ The class Point is a direct subclass of Object. 

¢ The class Object is the direct superclass of the class Point. 

¢ The class ColoredPoint is a direct subclass of class Point. 

¢ The class Point is the direct superclass of class ColoredPoint. 


The declaration of class Colored3dPoint causes a compile-time error because it attempts 
to extend the final class ColoredPoint. 


Example 8.1.4-2. Superclasses and Subclasses 


class Point { int x, y; } 
class ColoredPoint extends Point { int color; } 
final class Colored3dPoint extends ColoredPoint { int z; } 


Here, the relationships are as follows: 


¢ The class Point is a superclass of class ColoredPoint. 

¢ The class Point is a superclass of class Colored3dPoint. 

¢ The class ColoredPoint is a subclass of class Point. 

¢ The class ColoredPoint is a superclass of class Colored3dPoint. 


¢ The class Colored3dPoint is a subclass of class ColoredPoint. 
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¢ The class Colored3dPoint is a subclass of class Point. 


A class c directly depends on a type rT if T is mentioned in the extends or 
implements Clause of c either as a superclass or superinterface, or as a qualifier in 
the fully qualified form of a superclass or superinterface name. 


A class c depends on a reference type r if any of the following is true: 
¢ cdirectly depends on rT. 
¢ cdirectly depends on an interface r that depends (§9.1.3) on T. 


¢ c directly depends on a class p that depends on r (using this definition 
recursively). 


It is a compile-time error if a class depends on itself. 


If circularly declared classes are detected at run time, as classes are loaded, then a 
ClassCircularityError is thrown (§12.2.1). 


Example 8.1.4-3. Class Depends on Itself 


class Point extends ColoredPoint { int x, y; } 
class ColoredPoint extends Point { int color; } 


This program causes a compile-time error because class Point depends on itself. 


8.1.5 Superinterfaces 


The optional implements clause in a class declaration lists the names of interfaces 
that are direct superinterfaces of the class being declared. 


Superinterfaces: 
implements InterfaceTypeList 


InterfaceTypeList: 
InterfaceType {, InterfaceType} 


Each InterfaceType must name an accessible interface type ($6.6), or a compile- 
time error occurs. 


If an InterfaceType has type arguments, it must denote a well-formed parameterized 
type ($4.5), and none of the type arguments may be wildcard type arguments, or 
a compile-time error occurs. 
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It is a compile-time error if the same interface is mentioned as a direct 
superinterface more than once in a single implements clause. This is true even if 
the interface is named in different ways. 


Example 8.1.5-1. Illegal Superinterfaces 


class Redundant implements java.lang.Cloneable, Cloneable { 
int x; 


} 


This program results in a compile-time error because the names java.lang.Cloneable 
and Cloneable refer to the same interface. 


Given a (possibly generic) class declaration c<Fy,...,F,> (n = 0, Cc # Object), the 
direct superinterfaces of the class type C<Fj,...,.F;> are the types given in the 
implements clause of the declaration of c, if an implements clause is present. 


Given a generic class declaration C<F),...,F,> (m > 0), the direct superinterfaces of 
the parameterized class type C<Tj,...,T;>, where T; (1 <i <n) is a type, are all types 
I<; 9,...,U, 89>, where I<Uj,...,U,> 18 a direct superinterface of C<F ,...,F,> and 9 is 
the substitution [F,:=T,,...,Fni=Tnl- 


An interface type ris a superinterface of class type cif any of the following is true: 
* risa direct superinterface of c. 


¢ c has some direct superinterface 7 for which z is a superinterface, using the 
definition of "superinterface of an interface” given in §9.1.3. 


* risa superinterface of the direct superclass of c. 
A class can have a superinterface in more than one way. 
A class is said to implement all its superinterfaces. 


A class may not at the same time be a subtype of two interface types which are 
different parameterizations of the same generic interface (§9.1.2), or a subtype of 
a parameterization of a generic interface and a raw type naming that same generic 
interface, or a compile-time error occurs. 


This requirement was introduced in order to support translation by type erasure (§4.6). 


Example 8.1.5-2. Superinterfaces 


interface Colorable { 
void setColor(int color); 
int getColor(); 

} 

enum Finish { MATTE, GLOSSY } 
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interface Paintable extends Colorable { 
void setFinish(Finish finish); 
Finish getFinish(); 


class Point { int x, y; } 
class ColoredPoint extends Point implements Colorable { 
int color; 
public void setColor(int color) { this.color = color; } 
public int getColor() { return color; } 
} 
class PaintedPoint extends ColoredPoint implements Paintable { 
Finish finish; 
public void setFinish(Finish finish) { 
this.finish = finish; 
} 


public Finish getFinish() { return finish; } 


Here, the relationships are as follows: 


¢ The interface Paintable is a superinterface of class PaintedPoint. 


e The interface Colorable is a superinterface of class ColoredPoint and of class 
PaintedPoint. 


¢ The interface Paintable is a subinterface of the interface Colorable, and Colorable 
is a superinterface of Paintable, as defined in §9.1.3. 


The class PaintedPoint has Colorable as a superinterface both because it is a 
superinterface of ColoredPoint and because it is a superinterface of Paintable. 


Example 8.1.5-3. Illegal Multiple Inheritance of an Interface 


interface I<T> {} 
class B implements I<Integer> {} 
class C extends B implements I<String> {} 


Class c causes a compile-time error because it attempts to be a subtype of both I<Integer> 
and I<String>. 


Unless the class being declared is abstract, all the abstract member methods of 
each direct superinterface must be implemented (§8.4.8.1) either by a declaration in 
this class or by an existing method declaration inherited from the direct superclass 
or a direct superinterface, because a class that is not abstract is not permitted to 
have abstract methods (§8.1.1.1). 


Each default method (§9.4.3) of a superinterface of the class may optionally be 
overridden by a method in the class; if not, the default method is typically inherited 
and its behavior is as specified by its default body. 
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It is permitted for a single method declaration in a class to implement methods of 
more than one superinterface. 


Example 8.1.5-3. Implementing Methods of a Superinterface 


interface Colorable { 
void setColor(int color); 
int getColor(); 

} 

class Point { int x, y; }; 

class ColoredPoint extends Point implements Colorable { 
int color; 


This program causes a compile-time error, because ColoredPoint is not an abstract 
class but fails to provide an implementation of methods setColor and getColor of the 
interface Colorable. 


In the following program: 


interface Fish { int getNumberOfScales(); } 
interface Piano { int getNumberOfScales(); } 
class Tuna implements Fish, Piano { 
// You can tune a piano, but can you tuna fish? 
public int getNumberOfScales() { return 91; } 


the method getNumberOfScales inclass Tuna has a name, signature, and return type that 
matches the method declared in interface Fish and also matches the method declared in 
interface Piano; it is considered to implement both. 


On the other hand, in a situation such as this: 


interface Fish { int getNumberOfScales(); } 
interface StringBass { double getNumberOfScales(); } 
class Bass implements Fish, StringBass { 

// This declaration cannot be correct, 

// no matter what type is used. 

public ?? getNumberOfScales() { return 91; } 


it is impossible to declare a method named getNumberOfScales whose signature and 
return type are compatible with those of both the methods declared in interface Fish and 
in interface StringBass, because a class cannot have multiple methods with the same 
signature and different primitive return types (§8.4). Therefore, it is impossible for a single 
class to implement both interface Fish and interface St ringBass (§8.4.8). 
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8.1.6 Class Body and Member Declarations 


A class body may contain declarations of members of the class, that is, fields (§8.3), 
methods (§8.4), classes (§8.5), and interfaces (§8.5). 


A class body may also contain instance initializers (§8.6), static initializers (§8.7), 
and declarations of constructors (§8.8) for the class. 


ClassBody: 
{ {ClassBodyDeclaration} } 


ClassBodyDeclaration: 
ClassMemberDeclaration 
InstancelInitializer 
Staticlnitializer 
ConstructorDeclaration 


ClassMemberDeclaration: 
FieldDeclaration 
MethodDeclaration 
ClassDeclaration 
InterfaceDeclaration 


’ 


The scope and shadowing of a declaration of a member m declared in or inherited 
by aclass type c is specified in §6.3 and §6.4. 


If citself is a nested class, there may be definitions of the same kind (variable, method, or 
type) and name as min enclosing scopes. (The scopes may be blocks, classes, or packages.) 
In all such cases, the member m declared in or inherited by c shadows (§6.4.1) the other 
definitions of the same kind and name. 


8.2 Class Members 


The members of a class type are all of the following: 


¢ Members inherited from its direct superclass (§8.1.4), except in class Object, 
which has no direct superclass 


¢ Members inherited from any direct superinterfaces ($8.1.5) 


¢ Members declared in the body of the class (§8.1.6) 
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Members of a class that are declared private are not inherited by subclasses of 
that class. 


Only members of a class that are declared protected or public are inherited by 
subclasses declared in a package other than the one in which the class is declared. 


Constructors, static initializers, and instance initializers are not members and 
therefore are not inherited. 


We use the phrase the type of a member to denote: 
¢ Fora field, its type. 
¢ For a method, an ordered 4-tuple consisting of: 


— type parameters: the declarations of any type parameters of the method 
member. 


— argument types: a list of the types of the arguments to the method member. 
— return type: the return type of the method member. 


— throws clause: exception types declared in the throws clause of the method 
member. 


Fields, methods, and member types of a class type may have the same name, 
since they are used in different contexts and are disambiguated by different lookup 
procedures (§6.5). However, this is discouraged as a matter of style. 


Example 8.2-1. Use of Class Members 


class Point { 
int x, y; 
private Point() { reset(); } 
Point(int x, int y) { this.x = x; this.y = y; 
private void reset() { this.x = 0; this.y = 0; } 
} 
class ColoredPoint extends Point { 
int color; 
void clear() { reset(); } // error 
} 
class Test { 
public static void main(String[] args) { 
ColoredPoint c = new ColoredPoint(0, 0); // error 
c.reset(); // error 


} 


This program causes four compile-time errors. 
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One error occurs because ColoredPoint has no constructor declared with two int 
parameters, as requested by the use in main. This illustrates the fact that ColoredPoint 
does not inherit the constructors of its superclass Point. 


Another error occurs because ColoredPoint declares no constructors, and therefore a 
default constructor for it is implicitly declared (§8.8.9), and this default constructor is 
equivalent to: 


ColoredPoint() { super(); } 


which invokes the constructor, with no arguments, for the direct superclass of the class 
ColoredPoint. The error is that the constructor for Point that takes no arguments is 
private, and therefore is not accessible outside the class Point, even through a superclass 
constructor invocation (§8.8.7). 


Two more errors occur because the method reset of class Point is private, and therefore 
is not inherited by class ColoredPoint. The method invocations in method clear of class 
ColoredPoint and in method main of class Test are therefore not correct. 


Example 8.2-2. Inheritance of Class Members with Package Access 


Consider the example where the points package declares two compilation units: 


package points; 
public class Point { 
int x, y; 
public void move(int dx, int dy) { x += dx; y += dy; } 


and: 


package points; 
public class Point3d extends Point { 
aint oz} 
public void move(int dx, int dy, int dz) { 
x += dx; y += dy; z += dz; 


and a third compilation unit, in another package, is: 


import points.Point3d; 
class Point4d extends Point3d { 
int w; 
public void move(int dx, int dy, int dz, int dw) { 
x += dx; y += dy; z += dz; w += dw; // compile-time errors 
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Here both classes in the points package compile. The class Point 3d inherits the fields 
x and y of class Point, because it is in the same package as Point. The class Point 4d, 
which is in a different package, does not inherit the fields x and y of class Point or the 
field z of class Point 3d, and so fails to compile. 


A better way to write the third compilation unit would be: 


import points.Point3d; 
class Point4d extends Point3d { 
int w; 
public void move(int dx, int dy, int dz, int dw) { 
super.move (dx, dy, dz); w += dw; 


using the move method of the superclass Point 3d to process dx, dy, and dz. If Point4d 
is written in this way, it will compile without errors. 


Example 8.2-3. Inheritance of public and protected Class Members 
Given the class Point: 


package points; 
public class Point { 
public int x, y; 
protected int useCount = 0; 
static protected int totalUseCount = 0; 
public void move(int dx, int dy) { 
x += dx; y += dy; useCountt+t+; totalUseCount++; 


the public and protected fields x, y, useCount, and totalUseCount are inherited in 
all subclasses of Point. 


Therefore, this test program, in another package, can be compiled successfully: 


class Test extends points.Point { 
public void moveBack(int dx, int dy) { 
xX -= ax; y -= dy; useCount+t+; totalUseCount++; 


Example 8.2-4. Inheritance of private Class Members 


class Point { 
int x, y; 
void move(int dx, int dy) { 
x += ax; y += dy; totalMovest+; 
} 


private static int totalMoves; 
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void printMoves() { System.out.printin(totalMoves); } 
} 
class Point3d extends Point { 
ante2; 
void move(int dx, int dy, int dz) { 
super.move(dx, dy); z += dz; totalMovest+; // error 


Here, the class variable totalMoves can be used only within the class Point; it is not 
inherited by the subclass Point 3d. A compile-time error occurs because method move of 
class Point 3d tries to increment totalMoves. 


Example 8.2-5. Accessing Members of Inaccessible Classes 


Even though a class might not be declared public, instances of the class might be available 
at run time to code outside the package in which it is declared by means of a public 
superclass or superinterface. An instance of the class can be assigned to a variable of such a 
public type. An invocation of a public method of the object referred to by such a variable 
may invoke a method of the class if it implements or overrides a method of the public 
superclass or superinterface. (In this situation, the method is necessarily declared public, 
even though it is declared in a class that is not public.) 


Consider the compilation unit: 


package points; 
public class Point { 
public int x, y; 
public void move(int dx, int dy) { 
x += dx; y += dy; 


and another compilation unit of another package: 


package morePoints; 
class Point3d extends points.Point { 
public int z; 
public void move(int dx, int dy, int dz) { 
super.move(dx, dy); z += dz; 
} 
public void move(int dx, int dy) { 
move (dx, dy, 0); 


} 
public class OnePoint { 
public static points.Point getOne() { 
return new Point3d(); 
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An invocation morePoints.OnePoint.getOne() in yet a third package would return 
a Point3d that can be used as a Point, even though the type Point3d is not available 
outside the package morePoints. The two-argument version of method move could then be 
invoked for that object, which is permissible because method move of Point3d is public 
(as it must be, for any method that overrides a public method must itself be public, 
precisely so that situations such as this will work out correctly). The fields x and y of that 
object could also be accessed from such a third package. 


While the field z of class Point 3dis public, it is not possible to access this field from code 
outside the package morePoints, given only a reference to an instance of class Point3d 
in a variable p of type Point. This is because the expression p.z is not correct, as p has 
type Point and class Point has no field named z; also, the expression ( (Point3d)p) .z 
is not correct, because the class type Point3d cannot be referred to outside package 
morePoints. 


The declaration of the field z as public is not useless, however. If there were to be, in 
package morePoints, a public subclass Point 4d of the class Point 3d: 


package morePoints; 
public class Point4d extends Point3d { 
public int w; 
public void move(int dx, int dy, int dz, int dw) { 
super.move(dx, dy, dz); w += dw; 


then class Point 4d would inherit the field z, which, being public, could then be accessed 
by code in packages other than morePoints, through variables and expressions of the 
public type Point4d. 


8.3 Field Declarations 


The variables of a class type are introduced by field declarations. 


FieldDeclaration: 
{FieldModifier} UnannType VariableDeclaratorList ; 


VariableDeclaratorList: 
VariableDeclarator {, VariableDeclarator} 


VariableDeclarator: 
VariableDeclaratorld [= VariableInitializer] 


VariableDeclaratorld: 
Identifier [Dims] 
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Variablelnitializer: 
Expression 
Arraylnitializer 


UnannType: 
UnannPrimitiveType 
UnannReferenceType 


UnannPrimitiveType: 
NumericType 


boolean 


UnannReferenceType: 
UnannClassOrInterfaceType 
UnannTypeVariable 
UnannArrayType 


UnannClassOrInterfaceType: 
UnannClassType 
UnannInterfaceType 


UnannClassType: 
Typeldentifier [TypeArguments ] 
PackageName . {Annotation} Typeldentifier [TypeArguments] 
UnannClassOrInterfaceType . {Annotation} Typeldentifier 
[TypeArguments ] 


UnannInterfaceType: 
UnannClassType 


UnannTypeVariable: 
Typeldentifier 


UnannArrayType: 
UnannPrimitiveType Dims 
UnannClassOrInterfaceType Dims 
UnannTypeVariable Dims 


The following production from §4.3 is shown here for convenience: 


Dims: 
{Annotation} [ ] {{Annotation} [ |} 
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Each declarator in a FieldDeclaration declares one field. The Identifier in a 
declarator may be used in a name to refer to the field. 


More than one field may be declared in a single FieldDeclaration by using more 
than one declarator; the FieldModifiers and UnannType apply to all the declarators 
in the declaration. 


The FieldModifier clause is described in §8.3.1. 


The declared type of a field is denoted by UnannType if no bracket pairs appear in 
UnannType and VariableDeclaratorld, and is specified by §10.2 otherwise. 


The scope and shadowing of a field declaration is specified in §6.3 and $6.4. 


It is a compile-time error for the body of a class declaration to declare two fields 
with the same name. 


If a class declares a field with a certain name, then the declaration of that field is 
said to hide any and all accessible declarations of fields with the same name in 
superclasses, and superinterfaces of the class. 


In this respect, hiding of fields differs from hiding of methods (§8.4.8.3), for there is 
no distinction drawn between static and non-static fields in field hiding whereas a 
distinction is drawn between static and non-static methods in method hiding. 


A hidden field can be accessed by using a qualified name (§6.5.6.2) if itis static, 
or by using a field access expression that contains the keyword super (§15.11.2) 
or a cast to a superclass type. 


In this respect, hiding of fields is similar to hiding of methods. 


If a field declaration hides the declaration of another field, the two fields need not 
have the same type. 


A class inherits from its direct superclass and direct superinterfaces all the non- 
private fields of the superclass and superinterfaces that are both accessible (§6.6) 
to code in the class and not hidden by a declaration in the class. 


A private field of a superclass might be accessible to a subclass - for example, if 
both classes are members of the same class. Nevertheless, a private field is never 
inherited by a subclass. 


It is possible for a class to inherit more than one field with the same name, either 
from its superclass and superinterfaces or from its superinterfaces alone. Such a 
situation does not in itself cause a compile-time error. However, any attempt within 
the body of the class to refer to any such field by its simple name will result in a 
compile-time error, because the reference is ambiguous. 
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There might be several paths by which the same field declaration is inherited from 
an interface. In such a situation, the field is considered to be inherited only once, 
and it may be referred to by its simple name without ambiguity. 


A value stored in a field of type float is always an element of the float value set 
($4.2.3); similarly, a value stored in a field of type double is always an element 
of the double value set. It is not permitted for a field of type float to contain an 
element of the float-extended-exponent value set that is not also an element of the 
float value set, nor for a field of type double to contain an element of the double- 
extended-exponent value set that is not also an element of the double value set. 


Example 8.3-1. Multiply Inherited Fields 


A class may inherit two or more fields with the same name, either from its superclass and 
a superinterface or from two superinterfaces. A compile-time error occurs on any attempt 
to refer to any ambiguously inherited field by its simple name. A qualified name or a field 
access expression that contains the keyword super (§15.11.2) may be used to access such 
fields unambiguously. In the program: 


230£3" 4 
class SuperTest { int v = 3; } 
class Test extends SuperTest implements Frob { 


interface Frob { float v 


public static void main(String[] args) { 
new Test ().printV(); 

} 

void printV() { System.out.println(v); } 


the class Test inherits two fields named v, one from its superclass SuperTest and one 
from its superinterface Frob. This in itself is permitted, but a compile-time error occurs 
because of the use of the simple name v in method printv: it cannot be determined which 
v is intended. 


The following variation uses the field access expression super . v to refer to the field named 
v declared in class SuperTest and uses the qualified name Frob.v to refer to the field 
named v declared in interface Frob: 


interface Frob { float v = 2.0f; } 
class SuperTest { int v = 3; } 
class Test extends SuperTest implements Frob { 
public static void main(String[] args) { 
new Test ().printV(); 
} 
void printv() { 
System.out.printin((super.v + Frob.v)/2); 
} 


It compiles and prints: 
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Even if two distinct inherited fields have the same type, the same value, and are both 
final, any reference to either field by simple name is considered ambiguous and results 
in a compile-time error. In the program: 


interface Color { int RED=0, GREEN=1, BLUE=2; } 
interface TrafficLight { int RED=0, YELLOW=1, GREEN=2; } 
class Test implements Color, TrafficLight { 
public static void main(String[] args) { 
System.out.println(GREEN); // compile-time error 
System.out.printin (RED) ; // compile-time error 


it is not astonishing that the reference to GREEN should be considered ambiguous, because 
class Test inherits two different declarations for GREEN with different values. The point of 
this example is that the reference to RED is also considered ambiguous, because two distinct 
declarations are inherited. The fact that the two fields named RED happen to have the same 
type and the same unchanging value does not affect this judgment. 


Example 8.3-2. Re-inheritance of Fields 


If the same field declaration is inherited from an interface by multiple paths, the field is 
considered to be inherited only once. It may be referred to by its simple name without 
ambiguity. For example, in the code: 


interface Colorable { 
int RED = O0xff0000, GREEN = 0x00ff00, BLUE = Ox0000ff; 

} 

interface Paintable extends Colorable { 
int MATTE = 0, GLOSSY = 1; 

} 

class Point { int x, y; } 

class ColoredPoint extends Point implements Colorable {} 

class PaintedPoint extends ColoredPoint implements Paintable { 
int p = RED; 


the fields RED, GREEN, and BLUE are inherited by the class PaintedPoint both through 
its direct superclass ColoredPoint and through its direct superinterface Paintable. The 
simple names RED, GREEN, and BLUE may nevertheless be used without ambiguity within 
the class PaintedPoint to refer to the fields declared in interface Colorable. 
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8.3.1 Field Modifiers 


FieldModifier: 
(one of) 
Annotation public protected private 
static final transient volatile 


The rules for annotation modifiers on a field declaration are specified in 89.7.4 and 
§9.7.5. 


It is a compile-time error if the same keyword appears more than once as a modifier 
for a field declaration, or if a field declaration has more than one of the access 
modifiers public, protected, and private ($6.6). 


If two or more (distinct) field modifiers appear in a field declaration, it is customary, though 
not required, that they appear in the order consistent with that shown above in the production 
for FieldModifier. 


8.3.1.1 static Fields 


If a field is declared static, there exists exactly one incarnation of the field, no 
matter how many instances (possibly zero) of the class may eventually be created. 
A static field, sometimes called a class variable, is incarnated when the class is 
initialized (§12.4). 


A field that is not declared static (sometimes called a non-static field) is called 
an instance variable. Whenever a new instance of a class is created (§12.5), a new 
variable associated with that instance is created for every instance variable declared 
in that class or any of its superclasses. 


Example 8.3.1.1-1. static Fields 


class Point { 
int x, y, useCount; 
Point (int x, int y) { this.x = x; this.y = y; } 
static final Point origin = new Point(0, 0); 
} 
class Test { 
public static void main(String[] args) { 
Point p = new Point (1,1); 
Point q = new Point (2,2); 
p.x = 3; 
p-y = 3; 
p-.useCount+t; 
p.origin.useCount++; 
System.out sprint ini “be qx bo bogey be 
System.out.println(q.useCount) ; 
System.out.println(q.origin == Point.origin) ; 
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System.out.println(q.origin.useCount) ; 


This program prints: 


(2,2) 
0 
true 
1 


showing that changing the fields x, y, and useCount of p does not affect the fields of q, 
because these fields are instance variables in distinct objects. In this example, the class 
variable origin of the class Point is referenced both using the class name as a qualifier, in 
Point .origin, and using variables of the class type in field access expressions (§15.11), 
as in p.origin and q.origin. These two ways of accessing the origin class variable 
access the same object, evidenced by the fact that the value of the reference equality 
expression (§15.21.3): 


q.origin==Point.origin 
is true. Further evidence is that the incrementation: 
p.origin.useCount++; 


causes the value of q.origin.useCount to be 1; this is so because p.origin and 
q. origin refer to the same variable. 


Example 8.3.1.1-2. Hiding of Class Variables 


class Point { 
static int x = 2; 
} 
class Test extends Point { 
static double x = 4.7; 
public static void main(String[] args) { 
new Test ().printX(); 
} 
void printX() { 
System.out.println(x + " " + super.x); 


This program produces the output: 


because the declaration of x in class Test hides the definition of x in class Point, so class 
Test does not inherit the field x from its superclass Point. Within the declaration of class 
Test, the simple name x refers to the field declared within class Test. Code in class Test 
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may refer to the field x of class Point as super. x (or, because x is static, aS Point.x). 


If the declaration of Test . x is deleted: 


class Point { 
static int x = 2; 
} 
class Test extends Point { 
public static void main(String[] args) { 
new Test ().printX(); 
} 
void printX() { 
System.out.println(x + " " + super.x); 


then the field x of class Point is no longer hidden within class Test; instead, the simple 
name x now refers to the field Point .x. Code in class Test may still refer to that same 


field as super.x. Therefore, the output from this variant program is: 


Example 8.3.1.1-3. Hiding of Instance Variables 


class Point { 
int x = 2; 
} 
class Test extends Point { 
double x = 4.7; 
void printBoth() { 
System.out.println(x + " " + super.x); 
} 
public static void main(String[] args) { 
Test sample = new Test(); 
sample.printBoth (); 


System.out.println(sample.x + " " + ((Point) sample) . 


This program produces the output: 


bh 
ax 
i) 


x); 


because the declaration of x in class Test hides the definition of x in class Point, so class 
Test does not inherit the field x from its superclass Point. It must be noted, however, 
that while the field x of class Point is not inherited by class Test, it is nevertheless 
implemented by instances of class Test. In other words, every instance of class Test 
contains two fields, one of type int and one of type double. Both fields bear the name 
x, but within the declaration of class Test, the simple name x always refers to the field 
declared within class Test. Code in instance methods of class Test may refer to the 


instance variable x of class Point as super.x. 
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Code that uses a field access expression to access field x will access the field named x 
in the class indicated by the type of reference expression. Thus, the expression sample. x 
accesses a double value, the instance variable declared in class Test, because the type of 
the variable sample is Test, but the expression ( (Point) sample) .x accesses an int 
value, the instance variable declared in class Point, because of the cast to type Point. 


If the declaration of x is deleted from class Test, as in the program: 


class Point { 
static int x = 2; 
} 
class Test extends Point { 
void printBoth() { 
System.out.println(x + " " + super.x); 
} 
public static void main(String[] args) { 
Test sample = new Test(); 
sample.printBoth (); 
System.out.println(sample.x + " " + ((Point) sample) .x); 


then the field x of class Point is no longer hidden within class Test. Within instance 
methods in the declaration of class Test, the simple name x now refers to the field declared 
within class Point. Code in class Test may still refer to that same field as super.x. The 
expression sample. still refers to the field x within type Test, but that field is now an 
inherited field, and so refers to the field x declared in class Point. The output from this 
variant program is: 


i} 
i} 


8.3.1.2 final Fields 


A field can be declared fina (§4.12.4). Both class and instance variables (static 
and non-static fields) may be declared final. 


A blank final class variable must be definitely assigned by a static initializer of 
the class in which it is declared, or a compile-time error occurs (§8.7, §16.8). 


A blank final instance variable must be definitely assigned and moreover not 
definitely unassigned at the end of every constructor of the class in which it is 
declared, or a compile-time error occurs (§8.8, §16.9). 


8.3.1.3 transient Fields 


Variables may be marked transient to indicate that they are not part of the 
persistent state of an object. 
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Example 8.3.1.3-1. Persistence of transient Fields 


If an instance of the class Point: 


class Point { 
int x, y; 
transient float rho, theta; 


were saved to persistent storage by a system service, then only the fields x and y would be 
saved. This specification does not specify details of such services; see the specification of 
java.io.Serializable for an example of such a service. 


8.3.1.4 volatile Fields 


The Java programming language allows threads to access shared variables (§17.1). 
As a rule, to ensure that shared variables are consistently and reliably updated, a 
thread should ensure that it has exclusive use of such variables by obtaining a lock 
that, conventionally, enforces mutual exclusion for those shared variables. 


The Java programming language provides a second mechanism, volatile fields, 
that is more convenient than locking for some purposes. 


A field may be declared volatile, in which case the Java Memory Model ensures 
that all threads see a consistent value for the variable (§17.4). 


It is a compile-time error if a final variable is also declared volatile. 


Example 8.3.1.4-1. volatile Fields 


If, in the following example, one thread repeatedly calls the method one (but no more than 
Integer .MAX_VALUE times in all), and another thread repeatedly calls the method two: 


class Test { 
static int i= 0, j = 0; 
static void one() { i++; j++; } 
static void two() { 
System.out.printin("i=" + i + " G=" 4+ 4); 
} 
} 


then method two could occasionally print a value for j that is greater than the value of i, 
because the example includes no synchronization and, under the rules explained in §17.4, 
the shared values of i and j might be updated out of order. 


One way to prevent this out-or-order behavior would be to declare methods one and two 
to be synchronized (§8.4.3.6): 


class Test { 
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static int i= 0, j = 0; 

static synchronized void one() { i++; j++; } 

static synchronized void two() { 
System.out.printin("i=" + i + " j=" + 5); 


} 


This prevents method one and method two from being executed concurrently, and 
furthermore guarantees that the shared values of i and j are both updated before method 
one returns. Therefore method two never observes a value for j greater than that for i; 
indeed, it always observes the same value for i and 3. 


Another approach would be to declare i and 3 to be volatile: 


class Test { 


static volatile int i= 0, j = 0; 
static void one() { i++; j++; } 
static void two() { 


System.out.printin("i=" + i + " j=" 4+ 4); 


} 


This allows method one and method two to be executed concurrently, but guarantees that 
accesses to the shared values for i and 3 occur exactly as many times, and in exactly the 
same order, as they appear to occur during execution of the program text by each thread. 
Therefore, the shared value for j is never greater than that for i, because each update to 
i must be reflected in the shared value for i before the update to j occurs. It is possible, 
however, that any given invocation of method two might observe a value for 3 that is much 
greater than the value observed for i, because method one might be executed many times 
between the moment when method t wo fetches the value of i and the moment when method 
two fetches the value of 5. 


See §17.4 for more discussion and examples. 


8.3.2 Field Initialization 


If a declarator in a field declaration has a variable initializer, then the declarator 
has the semantics of an assignment (§15.26) to the declared variable. 


If the declarator is for a class variable (that is, a static field), then the following 
rules apply to its initializer: 


¢ It is acompile-time error if a reference by simple name to any instance variable 
occurs in the initializer. 


¢ It is a compile-time error if the keyword this (§15.8.3) or the keyword super 
(§15.11.2, $15.12) occurs in the initializer. 


e At run time, the initializer is evaluated and the assignment performed exactly 
once, when the class is initialized (§12.4.2). 
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Note that static fields that are constant variables (§4.12.4) are initialized before 
other static fields (§12.4.2). This also applies in interfaces (§9.3.1). When such 
fields are referenced by simple name, they will never be observed to have their 
default initial values (§4.12.5). 


If the declarator is for an instance variable (that is, a field that is not static), then 
the following rules apply to its initializer: 


The initializer may refer by simple name to any class variable declared in or 
inherited by the class, even one whose declaration occurs to the right of the 
initializer (§3.5). 


The initializer may refer to the current object using the keyword this (§$15.8.3) 
or the keyword super (§15.11.2, §15.12). 


At run time, the initializer is evaluated and the assignment performed each time 
an instance of the class is created (§12.5). 


References from variable initializers to fields that may not yet be initialized 
are subject to additional restrictions, as specified in §8.3.3 and §16 (Definite 
Assignment). 


Exception checking for a variable initializer in a field declaration is specified in 
§11.2.3. 


Variable initializers are also used in local variable declaration statements (§14.4), where 
the initializer is evaluated and the assignment performed each time the local variable 
declaration statement is executed. 


Example 8.3.2-1. Field Initialization 


class Point { 
int x = 1, y = 5; 
} 
class Test { 
public static void main(String[] args) { 
Point p = new Point (); 
System.out.println(p.x + ", "+ p.y); 


} 
This program produces the output: 
Lye 


because the assignments to x and y occur whenever a new Point is created. 
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Example 8.3.2-2. Forward Reference to a Class Variable 
class Test { 
float f = j; 


static int j = 1; 


} 


This program compiles without error; it initializes j to 1 when class Test is initialized, and 
initializes £ to the current value of j every time an instance of class Test is created. 


8.3.3 Restrictions on Field References in Initializers 


References to a field are sometimes restricted, even through the field is in scope. 
The following rules constrain forward references to a field (where the use textually 
precedes the field declaration) as well as self-reference (where the field is used in 
its own initializer). 


For a reference by simple name to a class variable f declared in class or interface 
c, it is a compile-time error if: 


¢ The reference appears either in a class variable initializer of c or in a static 
initializer of c (§8.7); and 


e The reference appears either in the initializer of fs own declarator or at a point 
to the left of £'s declarator; and 


¢ The reference is not on the left hand side of an assignment expression (§ 15.26); 
and 


¢ The innermost class or interface enclosing the reference is c. 


For a reference by simple name to an instance variable f declared in class c, it is 
a compile-time error if: 


¢ The reference appears either in an instance variable initializer of c or in an 
instance initializer of c (§8.6); and 


¢ The reference appears in the initializer of £'s own declarator or at a point to the 
left of +'s declarator; and 


¢ The reference is not on the left hand side of an assignment expression (§15.26); 
and 


¢ The innermost class enclosing the reference is c. 


Example 8.3.3-1. Restrictions on Field References 


A compile-time error occurs for this program: 
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class Testl1 { 
int i = 3; // compile-time error: 
// incorrect forward reference 


int j 1; 


whereas the following program compiles without error: 


class Test2 { 
Test2() { k = 2; } 


int j = 1; 
int i= j; 
int k; 


even though the constructor for Test 2 (§8.8) refers to the field k that is declared three 
lines later. 


The restrictions above are designed to catch, at compile time, circular or otherwise 
malformed initializations. Thus, both: 


class Z { 
Static ints y+ 23 
static int j = 4; 


and: 


class Z { 
Static { i. + 27: 3 
statie. Anti 7 
static { j = 4; } 


result in compile-time errors. Accesses by methods are not checked in this way, so: 


class Z { 
static int peek() { return 3; } 
static int i = peek(); 
static int j = 1; 
} 
class Test { 
public static void main(String[] args) { 
System.out.println(Z.i); 


produces the output: 
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because the variable initializer for i uses the class method peek to access the value of the 
variable j before 3 has been initialized by its variable initializer, at which point it still has 
its default value (§4.12.5). 


A more elaborate example is: 


class UseBeforeDeclaration { 
static { 
x = 100; 
// ok - assignment 
int y=x +1; 
// error — read before declaration 
int v = x = 3; 
// ok - x at left hand side of assignment 
int z = UseBeforeDeclaration.x * 2; 
// ok - not accessed via simple name 


Object o = new Object() { 


void foo() { xt++; } 
// ok - occurs in a different class 
{ xt++; } 


// ok - occurs in a different class 


3 = 200; 

// ok - assignment 
J ae dy 

// error - right hand side reads before declaration 
int k=j=j+ 1; 

// error — illegal forward reference to j 


int n = j = 300; 

// ok - j at left hand side of assignment 
int h = j++; 

// error — read before declaration 
ink T= this. * 3} 

// ok - not accessed via simple name 


Object o = new Object() { 
void foo(){ j+t; } 
// ok - occurs in a different class 
{3S gxtoly 4 
// ok - occurs in a different class 
‘i 


int w = x = 3; 
// ok - x at left hand side of assignment 
int p = x; 
// ok - instance initializers may access static fields 


static int u = 
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(new Object() { int bar() { return x; } })-.bar(); 
// ok - occurs in a different class 


static int. ix; 


int m= j = 4; 
// ok - 3 at left hand side of assignment 
int o = 
(new Object() { int bar() { return j; } })-bar(); 
// ok - occurs in a different class 
were) Soma 


8.4 Method Declarations 


A method declares executable code that can be invoked, passing a fixed number 
of values as arguments. 


MethodDeclaration: 
{MethodModifier} MethodHeader MethodBody 


MethodHeader: 
Result MethodDeclarator [Throws] 
TypeParameters {Annotation} Result MethodDeclarator [Throws] 


MethodDeclarator: 
Identifier ( [ReceiverParameter , ] [FormalParameterList] ) [Dims] 


ReceiverParameter: 
{Annotation} UnannType [Identifier .] this 


The following production from §4.3 is shown here for convenience: 


Dims: 
{Annotation} [| ] {{Annotation} [ |} 


The FormalParameterList clause is described in §8.4.1, the MethodModifier clause 
in §8.4.3, the TypeParameters clause in §8.4.4, the Result clause in §8.4.5, the 
Throws clause in §8.4.6, and the MethodBody in §8.4.7. 


The /dentifier in a MethodDeclarator may be used in a name to refer to the method 
($6.5.7.1, §15.12). 


The scope and shadowing of a method declaration is specified in §6.3 and §6.4. 
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The receiver parameter is an optional syntactic device for an instance method or an 
inner class's constructor. For an instance method, the receiver parameter represents 
the object for which the method is invoked. For an inner class's constructor, the 
receiver parameter represents the immediately enclosing instance of the newly 
constructed object. In both cases, the receiver parameter exists solely to allow the 
type of the represented object to be denoted in source code, so that the type may 
be annotated (§9.7.4). The receiver parameter is not a formal parameter; more 
precisely, it is not a declaration of any kind of variable (§4.12.3), it is never bound 
to any value passed as an argument in a method invocation expression or class 
instance creation expression, and it has no effect whatsoever at run time. 


A receiver parameter may appear either in the MethodDeclarator of an instance 
method or in the ConstructorDeclarator of a constructor of an inner class where 
the inner class is not declared in a static context (§8.1.3). If a receiver parameter 
appears in any other kind of method or constructor, then a compile-time error 
occurs. 


The type and name of a receiver parameter are constrained as follows: 


¢ In an instance method, the type of the receiver parameter must be the class or 
interface in which the method is declared, and the name of the receiver parameter 
must be this; otherwise, a compile-time error occurs. 


¢ In an inner class's constructor, the type of the receiver parameter must be the 
class or interface which is the immediately enclosing type declaration of the inner 
class, and the name of the receiver parameter must be /dentifier . this where 
Identifier is the simple name of the class or interface which is the immediately 
enclosing type declaration of the inner class; otherwise, a compile-time error 
occurs. 


It is a compile-time error for the body of a class declaration to declare as members 
two methods with override-equivalent signatures (§8.4.2). 


The declaration of a method that returns an array is allowed to place some or all 
of the bracket pairs that denote the array type after the formal parameter list. This 
syntax is supported for compatibility with early versions of the Java programming 
language. It is very strongly recommended that this syntax is not used in new code. 


8.4.1 Formal Parameters 


The formal parameters of a method or constructor, if any, are specified by a list 
of comma-separated parameter specifiers. Each parameter specifier consists of a 
type (optionally preceded by the final modifier and/or one or more annotations) 
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and an identifier (optionally followed by brackets) that specifies the name of the 
parameter. 


If a method or constructor has no formal parameters, and no receiver parameter, 
then an empty pair of parentheses appears in the declaration of the method or 
constructor. 


FormalParameterList: 
FormalParameter {, FormalParameter} 


FormalParameter: 
{ VariableModifier} UnannType VariableDeclaratorId 
VariableArityParameter 


VariableArity Parameter: 
{VariableModifier} UnannType {Annotation} ... Identifier 


VariableModifier: 
Annotation 


final 
The following productions from §8.3 and §4.3 are shown here for convenience: 


VariableDeclaratorld: 
Identifier [Dims] 


Dims: 
{Annotation} [| ] {{Annotation} [ |} 


A formal parameter of a method or constructor may be a variable arity parameter, 
indicated by an ellipsis following the type. At most one variable arity parameter 
is permitted for a method or constructor. It is a compile-time error if a variable 
arity parameter appears anywhere in the list of parameter specifiers except the last 
position. 


In the grammar for VariableArityParameter, note that the ellipsis (...) is a token unto 
itself ($3.11). Itis possible to put whitespace between it and the type, but this is discouraged 
as a matter of style. 


If the last formal parameter is a variable arity parameter, the method is a variable 
arity method. Otherwise, it is a fixed arity method. 


The rules for annotation modifiers on a formal parameter declaration and on a 
receiver parameter are specified in §9.7.4 and §9.7.5. 
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It is acompile-time error if final appears more than once as a modifier for a formal 
parameter declaration. 


The scope and shadowing of a formal parameter is specified in §6.3 and §6.4. 


It is a compile-time error for a method or constructor to declare two formal 
parameters with the same name. (That is, their declarations mention the same 
Identifier.) 


It is a compile-time error if a formal parameter that is declared final is assigned 
to within the body of the method or constructor. 


The declared type of a formal parameter depends on whether it is a variable arity 
parameter: 


¢ If the formal parameter is not a variable arity parameter, then the declared 
type is denoted by UnannType if no bracket pairs appear in UnannType and 
VariableDeclaratorld, and specified by §10.2 otherwise. 


¢ If the formal parameter is a variable arity parameter, then the declared type is an 
array type specified by $10.2. 


If the declared type of a variable arity parameter has a non-reifiable element 
type (§4.7), then a compile-time unchecked warning occurs for the declaration 
of the variable arity method, unless the method is annotated with @SafeVarargs 
(§9.6.4.7) or the warning is suppressed by @SuppressWarnings (§9.6.4.5). 


When the method or constructor is invoked (§15.12), the values of the actual 
argument expressions initialize newly created parameter variables, each of the 
declared type, before execution of the body of the method or constructor. The 
Identifier that appears in the FormalParameter may be used as a simple name in 
the body of the method or constructor to refer to the formal parameter. 


Invocations of a variable arity method may contain more actual argument 
expressions than formal parameters. All the actual argument expressions that do 
not correspond to the formal parameters preceding the variable arity parameter will 
be evaluated and the results stored into an array that will be passed to the method 
invocation (§15.12.4.2). 


A method's or constructor's formal parameter of type float always contains an 
element of the float value set (§4.2.3); similarly, a method's or constructor's formal 
parameter of type double always contains an element of the double value set. It 
is not permitted for a method's or constructor's formal parameter of type float 
to contain an element of the float-extended-exponent value set that is not also an 
element of the float value set, nor for a method's or constructor's formal parameter 


&.4 


245 


&.4 


246 


Method Declarations CLASSES 


of type double to contain an element of the double-extended-exponent value set 
that is not also an element of the double value set. 


Where an actual argument expression corresponding to a parameter variable is 
not FP-strict ($15.4), evaluation of that actual argument expression is permitted to 
use intermediate values drawn from the appropriate extended-exponent value sets. 
Prior to being stored in the parameter variable, the result of such an expression 
is mapped to the nearest value in the corresponding standard value set by being 
subjected to invocation conversion (§5.3). 


Here are some examples of receiver parameters in instance methods and inner classes' 
constructors: 


class Test { 
Test (/* ?? ?? */) {} 
// No receiver parameter is permitted in the constructor of 
// a top level class, as there is no conceivable type or name. 


void m(Test this) {} 
// OK: receiver parameter in an instance method 


static void n(Test this) {} 
// Tllegal: receiver parameter in a static method 


class A { 
A(Test Test.this) {} 
// OK: the receiver parameter represents the instance 
// of Test which immediately encloses the instance 
// of A being constructed. 


void m(A this) {} 
// OK: the receiver parameter represents the instance 
// of A for which A.m() is invoked. 


class B { 
B(Test.A A.this) {} 
// OK: the receiver parameter represents the instance 
// of A which immediately encloses the instance of B 
// being constructed. 


void m(Test.A.B this) {} 
// OK: the receiver parameter represents the instance 
// of B for which B.m() is invoked. 


B's constructor and instance method show that the type of the receiver parameter may be 
denoted with a qualified TypeName like any other type; but that the name of the receiver 
parameter in an inner class's constructor must use the simple name of the enclosing class. 
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8.4.2 Method Signature 


Two methods or constructors, w and n, have the same signature if they have the 
same name, the same type parameters (if any) (§8.4.4), and, after adapting the 
formal parameter types of w to the the type parameters of ™, the same formal 
parameter types. 


The signature of a method m, is a subsignature of the signature of a method mp if 
either: 


* mz has the same signature as m;, or 
¢ the signature of m; is the same as the erasure (§4.6) of the signature of mp. 


Two method signatures m, and mz are override-equivalent iff either m; is a 
subsignature of mz or mz is a subsignature of m;. 


It is a compile-time error to declare two methods with override-equivalent 
signatures in a class. 


Example 8.4.2-1. Override-Equivalent Signatures 


class Point { 
Ent: eX Ve 
abstract void move(int dx, int dy); 
void move(int dx, int dy) { x += dx; y += dy; } 


This program causes a compile-time error because it declares two move methods with the 
same (and hence, override-equivalent) signature. This is an error even though one of the 
declarations is abstract. 


The notion of subsignature is designed to express a relationship between two methods 
whose signatures are not identical, but in which one may override the other. Specifically, 
it allows a method whose signature does not use generic types to override any generified 
version of that method. This is important so that library designers may freely generify 
methods independently of clients that define subclasses or subinterfaces of the library. 


Consider the example: 


class CollectionConverter { 
List toList (Collection c) {...} 

} 

class Overrider extends CollectionConverter { 
List toList (Collection c) {...} 


Now, assume this code was written before the introduction of generics, and now the author 
of class CollectionConverter decides to generify the code, thus: 
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class CollectionConverter { 
<T> List<T> toList (Collection<T> c) {...} 
} 


Without special dispensation, Overrider.toList would no longer override 
CollectionConverter.toList. Instead, the code would be illegal. This would 
significantly inhibit the use of generics, since library writers would hesitate to migrate 
existing code. 


8.4.3 Method Modifiers 


MethodModifier: 
(one of) 
Annotation public protected private 


abstract static final synchronized native strictfp 


The rules for annotation modifiers on a method declaration are specified in §9.7.4 
and §9.7.5. 


It is a compile-time error if the same keyword appears more than once as a modifier 
for a method declaration, or if a method declaration has more than one of the access 
modifiers public, protected, and private ($6.6). 


It is a compile-time error if a method declaration that contains the keyword 
abstract also contains any one of the keywords private, static, final, native, 
strictfp, OF synchronized. 


It is a compile-time error if a method declaration that contains the keyword native 
also contains strictfp. 


If two or more (distinct) method modifiers appear in a method declaration, it is customary, 
though not required, that they appear in the order consistent with that shown above in the 
production for MethodModifier. 


8.4.3.1 abstract Methods 


An abstract method declaration introduces the method as a member, providing 
its signature (§8.4.2), result (§8.4.5), and throws clause if any (§8.4.6), but does 
not provide an implementation (§8.4.7). A method that is not abstract may be 
referred to as a concrete method. 


The declaration of an abstract method m must appear directly within an abstract 
class (call it a) unless it occurs within an enum declaration (§8.9); otherwise, a 
compile-time error occurs. 
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Every subclass of a that is not abst ract (§8.1.1.1) must provide an implementation 
for m, or a compile-time error occurs. 


An abstract class can override an abstract method by providing another 
abstract method declaration. 


This can provide a place to put a documentation comment, to refine the return type, or to 
declare that the set of checked exceptions that can be thrown by that method, when it is 
implemented by its subclasses, is to be more limited. 


An instance method that is not abstract can be overridden by an abstract 
method. 


Example 8.4.3.1-1. Abstract/Abstract Method Overriding 


class BufferEmpty extends Exception { 
BufferEmpty() { super(); } 
BufferEmpty (String s) { super(s); } 

} 

class BufferError extends Exception { 
BufferError() { super(); } 
BufferError(String s) { super(s); } 

} 

interface Buffer { 
char get() throws BufferEmpty, BufferError; 

} 

abstract class InfiniteBuffer implements Buffer { 
public abstract char get() throws BufferError; 


The overriding declaration of method get in class InfiniteBuffer states that method 
get in any subclass of InfiniteBuffer never throws a BufferEmpty exception, 
putatively because it generates the data in the buffer, and thus can never run out of data. 


Example 8.4.3.1-2. Abstract/Non-Abstract Overriding 


We can declare an abstract class Point that requires its subclasses to implement 
toString if they are to be complete, instantiable classes: 


abstract class Point { 
ant xy} 
public abstract String toString(); 


This abstract declaration of toString overrides the non-abstract toString method 
of class Object. (Class Object is the implicit direct superclass of class Point.) Adding 
the code: 


class ColoredPoint extends Point { 
int color; 
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public String toString() { 
return super.toString() + ": color "+ color; // error 


} 


results in a compile-time error because the invocation super.toString() refers to 
method toString in class Point, which is abstract and therefore cannot be invoked. 
Method toString of class Object can be made available to class ColoredPoint only if 
class Point explicitly makes it available through some other method, as in: 


abstract class Point { 

int x, y; 

public abstract String toString(); 

protected String objString() { return super.toString(); } 
} 
class ColoredPoint extends Point { 

int color; 

public String toString() { 

return objString() + ": color "+ color; // correct 


} 


8.4.3.2 static Methods 
A method that is declared static is called a class method. 


It is a compile-time error to use the name of a type parameter of any surrounding 
declaration in the header or body of a class method. 


A class method is always invoked without reference to a particular object. It is a 
compile-time error to attempt to refer to the current object using the keyword this 
(§15.8.3) or the keyword super (§15.11.2). 


A method that is not declared static is called an instance method, and sometimes 
called a non-static method. 


An instance method is always invoked with respect to an object, which becomes 
the current object to which the keywords this and super refer during execution 
of the method body. 


8.4.3.3 final Methods 
A method can be declared final to prevent subclasses from overriding or hiding it. 


It is a compile-time error to attempt to override or hide a final method. 


A private method and all methods declared immediately within a final class 
($8.1.1.2) behave as if they are final, since it is impossible to override them. 
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At run time, a machine-code generator or optimizer can "inline" the body of a final 
method, replacing an invocation of the method with the code in its body. The inlining 
process must preserve the semantics of the method invocation. In particular, if the target of 
an instance method invocation is nu11, then a NullPointerException must be thrown 
even if the method is inlined. A Java compiler must ensure that the exception will be thrown 
at the correct point, so that the actual arguments to the method will be seen to have been 
evaluated in the correct order prior to the method invocation. 


Consider the example: 


final class Point { 
int x, y; 
void move(int dx, int dy) { x += dx; y += dy; } 
} 
class Test { 
public static void main(String[] args) { 
Point[] p = new Point[100]; 
for (int i = 0; i < p.length; i++) { 
pli] = new Point(); 
pli].move(i, p.length-1-i); 


Inlining the method move of class Point in method main would transform the for loop 
to the form: 


for (int i = 0; i < p.length; i++) { 
pli] = new Point(); 
Point pi = pl[il; 
int j = p-.length-1-i; 
pi.x += i; 
pi.y += ji 


The loop might then be subject to further optimizations. 
Such inlining cannot be done at compile time unless it can be guaranteed that Test and 


Point will always be recompiled together, so that whenever Point - and specifically its 
move method - changes, the code for Test .main will also be updated. 


8.4.3.4 native Methods 


A method that is native is implemented in platform-dependent code, typically 
written in another programming language such as C. The body of a native method 
is given as a semicolon only, indicating that the implementation is omitted, instead 
of a block (§8.4.7). 


For example, the class RandomAccessFile of the package java.io might declare the 
following native methods: 
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package java.io; 


public class RandomAccessFile 


8.4.3.5 


impl 
publ 
publ 
publ 
publ 
publ 


publ 
publ 


ements DataOutput, DataInput { 


ic native void open(String name, boolean writeable) 
throws IOException; 

ic native int readBytes(byte[] b, int off, int len) 
throws IOException; 

ic native void writeBytes(byte[] b, int off, int len) 
throws IOException; 

ic native long getFilePointer() throws IOException; 
ic native void seek(long pos) throws IOException; 

ic native long length() throws IOException; 

ic native void close() throws IOException; 


strictfp Methods 
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The effect of the strictfp modifier is to make all float or double expressions 
within the method body be explicitly FP-strict ($15.4). 


8.4.3.6 


synchronized Methods 


A synchronized method acquires a monitor ($17.1) before it executes. 


For a class (static) method, the monitor associated with the class object for the 
method's class is used. 


For an instance method, the monitor associated with this (the object for which the 
method was invoked) is used. 


Example 8.4.3.6-1. synchronized Monitors 


These are the same monitors that can be used by the synchronized statement ($14.19). 


Thus, the code: 


class Test { 


int count; 

synchronized void bump() { 
count+t++t+; 

} 

static int classCount; 

static synchronized void classBump() { 
classCount++; 


has exactly the same effect as: 
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class BumpTest { 
int count; 
void bump() { 
synchronized (this) { count++t; } 
} 


static int classCount; 


static void classBump() { 
try { 
synchronized (Class.forName("BumpTest")) { 
classCount++; 


} 
} catch (ClassNotFoundException e) {} 


Example 8.4.3.6-2. synchronized Methods 


public class Box { 

private Object boxContents; 

public synchronized Object get() { 
Object contents = boxContents; 
boxContents = null; 
return contents; 

} 

public synchronized boolean put (Object contents) { 
if (boxContents != null) return false; 
boxContents = contents; 
return true; 


This program defines a class which is designed for concurrent use. Each instance of the 
class Box has an instance variable boxContents that can hold a reference to any object. 
You can put an object in a Box by invoking put, which returns false if the box is already 
full. You can get something out of a Box by invoking get, which returns a null reference 
if the box is empty. 


If put and get were not synchronized, and two threads were executing methods for 
the same instance of Box at the same time, then the code could misbehave. It might, for 
example, lose track of an object because two invocations to put occurred at the same time. 


8.4.4 Generic Methods 


A method is generic if it declares one or more type variables (§4.4). 


These type variables are known as the type parameters of the method. The form of 
the type parameter section of a generic method is identical to the type parameter 
section of a generic class (§8.1.2). 


A generic method declaration defines a set of methods, one for each possible 
invocation of the type parameter section by type arguments. Type arguments may 
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not need to be provided explicitly when a generic method is invoked, as they can 
often be inferred (§18 (Type Inference)). 


The scope and shadowing of a method's type parameter is specified in $6.3. 


Two methods or constructors wand w have the same type parameters if both of the 
following are true: 


¢ mand whave same number of type parameters (possibly zero). 


¢ Where A), ..., A, are the type parameters of mand B,, ..., B, are the type parameters 
of n, let 9=/B,7=A,, ..., B,/=A,]. Then, for all i (1 <i <n), the bound of a; is the 
same type as 9 applied to the bound of B;. 


Where two methods or constructors u and w have the same type parameters, a type 
mentioned in can be adapted to the type parameters of mby applying 9, as defined 
above, to the type. 


8.4.5 Method Result 


The result of a method declaration either declares the type of value that the method 
returns (the return type), or uses the keyword void to indicate that the method does 
not return a value. 


Result: 
UnannType 


void 


If the result is not void, then the return type of a method is denoted by UnannType 
if no bracket pairs appear after the formal parameter list, and is specified by $10.2 
otherwise. 


Return types may vary among methods that override each other if the return types 
are reference types. The notion of return-type-substitutability supports covariant 
returns, that is, the specialization of the return type to a subtype. 


A method declaration d; with return type R; is return-type-substitutable for another 
method a, with return type 2 iff any of the following is true: 


e If R, is void then R> iS void. 
¢ If R, is a primitive type then R2 is identical to R;. 
e If Rr, is a reference type then one of the following is true: 


— R;, adapted to the type parameters of dz (8.4.4), is a subtype of Ro. 
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— R; can be converted to a subtype of R2 by unchecked conversion (§5.1.9). 


— d, does not have the same signature as dz (§8.4.2), and R; = |R2]. 


An unchecked conversion is allowed in the definition, despite being unsound, as a special 
allowance to allow smooth migration from non-generic to generic code. If an unchecked 
conversion is used to determine that R; is return-type-substitutable for R2, then R; is 
necessarily not a subtype of R2 and the rules for overriding (§8.4.8.3, §9.4.1) will require 
a compile-time unchecked warning. 


8.4.6 Method Throws 


A throws Clause is used to denote any checked exception classes (§11.1.1) that the 
statements in a method or constructor body can throw (§11.2.2). 


Throws: 
throws ExceptionTypeList 


ExceptionTypeList: 
ExceptionType {, ExceptionType} 


ExceptionType: 
ClassType 
TypeVariable 


It is a compile-time error if an ExceptionType mentioned in a throws clause is not 
a subtype (§4.10) of Throwable. 


Type variables are allowed in a throws clause even though they are not allowed 
in a catch Clause ($14.20). 


It is permitted but not required to mention unchecked exception classes ($11.1.1) 
in a throws Clause. 


The relationship between a throws clause and the exception checking for a method 
or constructor body is specified in §11.2.3. 


Essentially, for each checked exception that can result from execution of the body of a 
method or constructor, a compile-time error occurs unless its exception type or a supertype 
of its exception type is mentioned in a throws clause in the declaration of the method or 
constructor. 


The requirement to declare checked exceptions allows a Java compiler to ensure that code 
for handling such error conditions has been included. Methods or constructors that fail to 
handle exceptional conditions thrown as checked exceptions in their bodies will normally 
cause compile-time errors if they lack proper exception types in their throws clauses. The 
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Java programming language thus encourages a programming style where rare and otherwise 
truly exceptional conditions are documented in this way. 


The relationship between the throws clause of a method and the throws clauses of 
overridden or hidden methods is specified in §8.4.8.3. 


Example 8.4.6-1. Type Variables as Thrown Exception Types 


import java.io.FileNotFoundException; 
interface PrivilegedExceptionAction<E extends Exception> { 
void run() throws E; 
} 
class AccessController { 
public static <E extends Exception> 
Object doPrivileged (PrivilegedExceptionAction<E> action) throws E { 
action.run(); 
return "success"; 


} 
class Test { 
public static void main(String[] args) { 

try { 

AccessController.doPrivileged ( 

new PrivilegedExceptionAction<FileNotFoundException>() { 
public void run() throws FileNotFoundException { 
// ... delete a file 


); 
} catch (FileNotFoundException f) { /* Do something */ } 


8.4.7 Method Body 


A method body is either a block of code that implements the method or simply a 
semicolon, indicating the lack of an implementation. 


MethodBody: 
Block 


’ 


The body of a method must be a semicolon if the method is abstract or native 
($8.4.3.1, §8.4.3.4). More precisely: 


¢ It is a compile-time error if a method declaration is either abstract or native 
and has a block for its body. 


¢ It is acompile-time error if a method declaration is neither abst ract nor native 
and has a semicolon for its body. 


256 


CLASSES Method Declarations 


If an implementation is to be provided for a method declared void, but the implementation 
requires no executable code, the method body should be written as a block that contains 
no statements: "{ }". 


The rules for return statements in a method body are specified in §14.17. 


If a method is declared to have a return type (§8.4.5), then a compile-time error 
occurs if the body of the method can complete normally (§14.1). 


In other words, a method with a return type must return only by using a return statement 
that provides a value return; the method is not allowed to "drop off the end of its body". 
See §14.17 for the precise rules about return statements in a method body. 


It is possible for a method to have a return type and yet contain no return statements. 
Here is one example: 


class DizzyDean { 
int pitch() { throw new RuntimeException("90 mph?!"); } 
} 


8.4.8 Inheritance, Overriding, and Hiding 


A class c inherits from its direct superclass all concrete methods m (both static 
and instance) of the superclass for which all of the following are true: 


* mis a member of the direct superclass of c. 


* miS public, protected, or declared with package access in the same package 
as C. 


¢ No method declared in c has a signature that is a subsignature (§8.4.2) of the 
signature of m. 


A class c inherits from its direct superclass and direct superinterfaces all abstract 
and default ($9.4) methods m for which all of the following are true: 


* mis a member of the direct superclass or a direct superinterface, p, of c. 


* miS public, protected, or declared with package access in the same package 
as C. 


¢ No method declared in c has a signature that is a subsignature (§8.4.2) of the 
signature of m. 


¢ No concrete method inherited by c from its direct superclass has a signature that 
is a subsignature of the signature of m. 
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¢ There exists no method m' that is a member of the direct superclass or a direct 
superinterface, p', of c(mdistinct from m’, p distinct from p'), such that m' overrides 
from p' (§8.4.8.1, §9.4.1.1) the declaration of the method m. 


A class does not inherit private or static methods from its superinterfaces. 


Note that methods are overridden or hidden on a signature-by-signature basis. If, for 
example, a class declares two public methods with the same name (§8.4.9), and a subclass 
overrides one of them, the subclass still inherits the other method. 


Example 8.4.8-1. Inheritance 


interface I1 { 
int foo(); 


} 


interface I2 { 
int foo(); 


} 


abstract class Test implements I1, 12 {} 


Here, the abstract class Test inherits the abstract method foo from interface I1 and 
also the abstract method foo from interface 12. The key question in determining the 
inheritance of foo from 11 is: does the method foo in 12 override "from 12" (§9.4.1.1) 
the method foo in 11? No, because 11 and 12 are not subinterfaces of each other. Thus, 
from the viewpoint of class Test, the inheritance of foo from 11 is unfettered; similarly 
for the inheritance of foo from 12. Per §8.4.8.4, class Test can inherit both foo methods; 
obviously it must be declared abstract, or else override both abstract foo methods 
with a concrete method. 


Note that it is possible for an inherited concrete method to prevent the inheritance of an 
abstract or default method. (The concrete method will override the abst ract or default 
method "from c", per §8.4.8.1 and §9.4.1.1.) Also, it is possible for one supertype method 
to prevent the inheritance of another supertype method if the former "already" overrides 
the latter - this is the same as the rule for interfaces (§9.4.1), and prevents conflicts in 
which multiple default methods are inherited and one implementation is clearly meant to 
supersede the other. 


8.4.8.1 Overriding (by Instance Methods) 


An instance method m- declared in or inherited by class c, overrides from c another 
method m, declared in class a, iff all of the following are true: 


¢ cisa subclass of a. 
¢ cdoes not inherit ma. 
¢ The signature of mc is a subsignature ($8.4.2) of the signature of ma. 


¢ One of the following is true: 
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— maiS public. 
— ma iS protected. 


— ma is declared with package access in the same package as c, and either c 
declares mc or ma is a member of the direct superclass of c. 


— ma is declared with package access and mc overrides mg from some superclass 
of c. 


— ma is declared with package access and mc overrides a method m' from c (m' 
distinct from mc and ma), such that m' overrides m, from some superclass of c. 


If mc is non-abstract and overrides from c an abstract method mag, then mc is said 
to implement ma from c. 


It is a compile-time error if the overridden method, ma, is a static method. 


In this respect, overriding of methods differs from hiding of fields (§8.3), for it is 
permissible for an instance variable to hide a static variable. 


An instance method m- declared in or inherited by class c, overrides from c another 
method m; declared in interface 1, iff all of the following are true: 


* risa superinterface of c. 

¢ m;is not static. 

¢ cdoes not inherit m;. 

¢ The signature of mc is a subsignature ($8.4.2) of the signature of mr. 


* mris public. 


The signature of an overriding method may differ from the overridden one if a formal 
parameter in one of the methods has a raw type, while the corresponding parameter in the 
other has a parameterized type. This accommodates migration of pre-existing code to take 
advantage of generics. 


The notion of overriding includes methods that override another from some subclass of 
their declaring class. This can happen in two ways: 


¢ A concrete method in a generic superclass can, under certain parameterizations, have 
the same signature as an abstract method in that class. In this case, the concrete method 
is inherited and the abstract method is not (as described above). The inherited 
method should then be considered to override its abstract peer from c. (This scenario is 
complicated by package access: if c is in a different package, then m, would not have 
been inherited anyway, and should not be considered overridden.) 


¢ A method inherited from a class can override a superinterface method. (Happily, package 
access is not a concern here.) 
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An overridden method can be accessed by using a method invocation expression 
($15.12) that contains the keyword super. A qualified name or a cast to a superclass 
type is not effective in attempting to access an overridden method. 


In this respect, overriding of methods differs from hiding of fields. 


The presence or absence of the strict fp modifier has absolutely no effect on the 
rules for overriding methods and implementing abstract methods. For example, it 
is permitted for a method that is not FP-strict to override an FP-strict method and 
it is permitted for an FP-strict method to override a method that is not FP-strict. 


Example 8.4.8.1-1. Overriding 


class Point { 


} 


int x = 0, y = 0; 
void move(int dx, int dy) { x += dx; y += dy; 


class SlowPoint extends Point { 


Here, the class SlowPoint overrides the declarations of method move of class Point with 
its own move method, which limits the distance that the point can move on each invocation 
of the method. When the move method is invoked for an instance of class SlowPoint, the 
overriding definition in class SlowPoint will always be called, even if the reference to the 


int xLimit, yLimit; 
void move(int dx, int dy) { 


super.move (limit (dx, xLimit), limit(dy, yLimit)); 


} 


static int limit(int d, int limit) { 


return d > limit ? limit : d < -limit ? -limit 


SlowPoint object is taken from a variable whose type is Point. 


Example 8.4.8.1-2. Overriding 


Overriding makes it easy for subclasses to extend the behavior of an existing class, as shown 


in this example: 


import java.io.OutputStream; 


import java.io.IOException; 


class BufferOutput { 


private OutputStream 0; 
BufferOutput (OutputStream o) { this.o = o; } 
protected byte[] buf = new byte[512]; 
protected int pos = 0; 
public void putchar(char c) throws IOException 
if (pos == buf.length) flush(); 
buf [pos++] = (byte)c; 


} 
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public void putstr(String s) throws IOException { 
for (int i = 0; i < s.length(); i++) 
putchar(s.charAt (i)); 
} 
public void flush() throws IOException { 
o.write(buf, 0, pos); 
pos = 0; 


} 
class LineBufferOutput extends BufferOutput { 
LineBufferOutput (OutputStream o) { super(o); } 
public void putchar(char c) throws IOException { 
super.putchar(c); 
if (c == '\n') flush(); 


} 
class Test { 
public static void main(String[] args) throws IOException { 
LineBufferOutput lbo = new LineBufferOutput (System.out) ; 
lbo.putstr("lbo\nlbo") ; 
System.out.print ("print\n") ; 
lbo.putstr("\n"); 


This program produces the output: 


lbo 
print 
lbo 


The class BufferOutput implements a very simple buffered version of an 
OutputStream, flushing the output when the buffer is full or flush is invoked. The 
subclass LineBufferOutput declares only a constructor and a single method put char, 
which overrides the method putchar of BufferOutput. It inherits the methods putstr 
and flush from class BufferOutput. 


In the putchar method of a LineBufferOutput object, if the character argument is a 
newline, then it invokes the flush method. The critical point about overriding in this 
example is that the method put st r, which is declared in class Buf ferOut put, invokes the 
put char method defined by the current object this, which is not necessarily the put char 
method declared in class BufferOutput. 


Thus, when putstr is invoked in main using the LineBufferOutput object lbo, the 
invocation of put char in the body of the put st r method is an invocation of the putchar 
of the object 1bo, the overriding declaration of put char that checks for a newline. This 
allows a subclass of BufferOutput to change the behavior of the put st r method without 
redefining it. 


Documentation for a class such as BufferOutput, which is designed to be extended, 
should clearly indicate what is the contract between the class and its subclasses, and 
should clearly indicate that subclasses may override the putchar method in this way. 
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The implementor of the BufferOutput class would not, therefore, want to change the 
implementation of put str in a future implementation of BufferOutput not to use the 
method put char, because this would break the pre-existing contract with subclasses. See 
the discussion of binary compatibility in §13 (Binary Compatibility), especially §13.2. 


8.4.8.2 Hiding (by Class Methods) 


If aclass c declares or inherits a stat ic method m, then mis said to hide any method 
m', where the signature of m is a subsignature (§8.4.2) of the signature of m', in 
the superclasses and superinterfaces of c that would otherwise be accessible (§6.6) 
to code in c. 


It is a compile-time error if a static method hides an instance method. 


In this respect, hiding of methods differs from hiding of fields (§8.3), for it is permissible 
for a static variable to hide an instance variable. Hiding is also distinct from shadowing 
(§6.4.1) and obscuring (§6.4.2). 


A hidden method can be accessed by using a qualified name or by using a method 
invocation expression (§15.12) that contains the keyword super or a cast to a 
superclass type. 


In this respect, hiding of methods is similar to hiding of fields. 
Example 8.4.8.2-1. Invocation of Hidden Class Methods 


A class (static) method that is hidden can be invoked by using a reference whose type 
is the class that actually contains the declaration of the method. In this respect, hiding of 
static methods is different from overriding of instance methods. The example: 


class Super { 
static String greeting() { return "Goodnight"; } 
String name() { return "Richard"; } 
} 
class Sub extends Super { 
static String greeting() { return "Hello"; } 
String name() { return "Dick"; } 
} 
class Test { 
public static void main(String[] args) { 
Super s = new Sub(); 
System.out.println(s.greeting() + ", " + s.name()); 


produces the output: 


Goodnight, Dick 
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because the invocation of greeting uses the type of s, namely Super, to figure out, at 
compile time, which class method to invoke, whereas the invocation of name uses the class 
of s, namely Sub, to figure out, at run time, which instance method to invoke. 


8.4.8.3 Requirements in Overriding and Hiding 


If a method declaration a; with return type R; overrides or hides the declaration of 
another method a, with return type R2, then d; must be return-type-substitutable 
(§8.4.5) for dz, or a compile-time error occurs. 


This rule allows for covariant return types - refining the return type of a method when 
overriding it. 


If R; is not a subtype of R»2, then a compile-time unchecked warning occurs, unless 
suppressed by @SuppressWarnings (§9.6.4.5). 


A method that overrides or hides another method, including methods that 
implement abstract methods defined in interfaces, may not be declared to throw 
more checked exceptions than the overridden or hidden method. 


In this respect, overriding of methods differs from hiding of fields (§8.3), for it is 
permissible for a field to hide a field of another type. 


More precisely, suppose that B is a class or interface, and a is a superclass or 
superinterface of 8, and a method declaration mz in B overrides or hides a method 
declaration m, in a. Then: 


¢ If m; has a throws clause that mentions any checked exception types, then m, 
must have a throws clause, or a compile-time error occurs. 


¢ For every checked exception type listed in the throws clause of mz, that same 
exception class or one of its supertypes must occur in the erasure (§4.6) of the 
throws Clause of m;; otherwise, a compile-time error occurs. 


e If the unerased throws clause of m, does not contain a supertype of each 
exception type in the throws clause of mz (adapted, if necessary, to the type 
parameters of m;), then a compile-time unchecked warning occurs, unless 
suppressed by @SuppressWarnings (§9.6.4.5). 


It is a compile-time error if a type declaration r has a member method m, and there 
exists a method mz declared in T or a supertype of 7 such that all of the following 
are true: 


¢ m,and m; have the same name. 


* mz is accessible (§6.6) from T. 
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¢ The signature of m; is not a subsignature (§$8.4.2) of the signature of mp. 


¢ The signature of m, or some method m, overrides (directly or indirectly) has the 


same erasure as the signature of mz or some method mz overrides (directly or 
indirectly). 


These restrictions are necessary because generics are implemented via erasure. The rule 
above implies that methods declared in the same class with the same name must have 
different erasures. It also implies that a type declaration cannot implement or extend two 
distinct invocations of the same generic interface. 


The access modifier of an overriding or hiding method must provide at least as 
much access as the overridden or hidden method, as follows: 


¢ If the overridden or hidden method is public, then the overriding or hiding 


method must be public; otherwise, a compile-time error occurs. 


¢ If the overridden or hidden method is protected, then the overriding or hiding 


method must be protected or public; otherwise, a compile-time error occurs. 


¢ If the overridden or hidden method has package access, then the overriding or 


hiding method must not be private; otherwise, a compile-time error occurs. 


Note that a private method cannot be overridden or hidden in the technical sense of 
those terms. This means that a subclass can declare a method with the same signature as 
a private method in one of its superclasses, and there is no requirement that the return 
type or throws clause of such a method bear any relationship to those of the private 
method in the superclass. 


Example 8.4.8.3-1. Covariant Return Types 


The following declarations are legal in the Java programming language from Java SE 5.0 
onwards: 


class C implements Cloneable { 
C copy() throws CloneNotSupportedException { 
return (C)clone(); 


} 


class D extends C implements Cloneable { 
D copy() throws CloneNotSupportedException { 
return (D)clone(); 


The relaxed rule for overriding also allows one to relax the conditions on abstract classes 
implementing interfaces. 
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Example 8.4.8.3-2. Unchecked Warning from Return Type 
Consider: 


class StringSorter { 
// turns a collection of strings into a sorted list 
List toList (Collection c) {...} 


and assume that someone subclasses St ringSorter: 


class Overrider extends StringSorter { 
List toList (Collection c) {...} 


Now, at some point the author of StringSorter decides to generify the code: 


class StringSorter { 
// turns a collection of strings into a sorted list 
List<String> toList (Collection<String> c) {...} 


An unchecked warning would be given when compiling Overrider against the new 
definition of StringSorter because the return type of Overrider.toList is List, 
which is not a subtype of the return type of the overridden method, List<String>. 


Example 8.4.8.3-3. Incorrect Overriding because of throws 


This program uses the usual and conventional form for declaring a new exception type, in 
its declaration of the class BadPointException: 


class BadPointException extends Exception { 
BadPointException() { super(); } 
BadPointException(String s) { super(s); } 
} 
class Point { 
int x, y; 
void move(int dx, int dy) { x += dx; y += dy; } 
} 
class CheckedPoint extends Point { 
void move(int dx, int dy) throws BadPointException { 
if ((x + dx) <0 || (y + dy) < 0) 
throw new BadPointException (); 
x += dx; y += dy; 


The program results in a compile-time error, because the override of method move in class 
CheckedPoint declares that it will throw a checked exception that the move in class Point 
has not declared. If this were not considered an error, an invoker of the method move on 
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a reference of type Point could find the contract between it and Point broken if this 
exception were thrown. 


Removing the throws clause does not help: 


class CheckedPoint extends Point { 
void move(int dx, int dy) { 
if ((x + dx) <0 || (y + dy) < 0) 
throw new BadPointException (); 
x += dx; y += dy; 


A different compile-time error now occurs, because the body of the method move cannot 
throw a checked exception, namely BadPointException, that does not appear in the 
throws Clause for move. 


Example 8.4.8.3-4. Erasure Affects Overriding 


A class cannot have two member methods with the same name and type erasure: 


class C<T> { 
Tae. (Pf ky teed 

} 

class D extends C<String> { 
Object id(Object x) {...} 


This is illegal since D.id(Object) is a member of D, C<String>.id(String) is 
declared in a supertype of D, and: 


¢ The two methods have the same name, id 
* C<String>.id(String) is accessible to D 


¢ The signature of D.id(Object) is not a _ subsignature of that of 
C<String>.id(String) 


¢ The two methods have the same erasure 
Two different methods of a class may not override methods with the same erasure: 


class C<T> { 
Ta? Sebo face o} 
} 
interface I<T> { 
T id(T x); 
} 
class D extends C<String> implements I<Integer> { 
public String 1d\(String) x) {...] 
public Integer id(Integer x) {...} 
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This is also illegal, since D.id (String) is a member of D, D.id(Integer) is declared 
in D, and: 

¢ The two methods have the same name, id 

* D.id(Integer) is accessible to D 


¢ The two methods have different signatures (and neither is a subsignature of the other) 


* D.id(String) overrides C<String>.id(String) and D.id(Integer) overrides 
I.id(Integer) yet the two overridden methods have the same erasure 


8.4.8.4 Inheriting Methods with Override-Equivalent Signatures 


It is possible for a class to inherit multiple methods with override-equivalent 
signatures (§8.4.2). 


It is a compile-time error if a class c inherits a concrete method whose signature is 
override-equivalent with another method inherited by c. 


It is a compile-time error if a class c inherits a default method whose signature 
is override-equivalent with another method inherited by c, unless there exists an 
abstract method declared in a superclass of c and inherited by c that is override- 
equivalent with the two methods. 


This exception to the strict default-abstract and default-default conflict rules is made 
when an abst ract method is declared in a superclass: the assertion of abstract-ness coming 
from the superclass hierarchy essentially trumps the default method, making the default 
method act as if it were abstract. However, the abstract method from a class does not 
override the default method(s), because interfaces are still allowed to refine the signature 
of the abstract method coming from the class hierarchy. 


Note that the exception does not apply if all override-equivalent abstract methods 
inherited by c were declared in interfaces. 


Otherwise, the set of override-equivalent methods consists of at least one abstract 
method and zero or more default methods; then the class is necessarily an abstract 
class and is considered to inherit all the methods. 


One of the inherited methods must be return-type-substitutable for every other 
inherited method; otherwise, a compile-time error occurs. (The throws clauses do 
not cause errors in this case.) 


There might be several paths by which the same method declaration is inherited 
from an interface. This fact causes no difficulty and never, of itself, results in a 
compile-time error. 
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8.4.9 Overloading 


If two methods of a class (whether both declared in the same class, or both inherited 
by a class, or one declared and one inherited) have the same name but signatures 
that are not override-equivalent, then the method name is said to be overloaded. 


This fact causes no difficulty and never of itself results in a compile-time error. 
There is no required relationship between the return types or between the throws 
clauses of two methods with the same name, unless their signatures are override- 
equivalent. 


When a method is invoked (§15.12), the number of actual arguments (and any 
explicit type arguments) and the compile-time types of the arguments are used, 
at compile time, to determine the signature of the method that will be invoked 
(§15.12.2). If the method that is to be invoked is an instance method, the actual 


method to be invoked will be determined at run time, using dynamic method lookup 
($15.12.4). 


Example 8.4.9-1. Overloading 


class Point { 
float x, y; 
void move(int dx, int dy) { x += dx; y += dy; } 
void move(float dx, float dy) { x += dx; y += dy; } 
public String toString() { return "("+x+","+y+")"; } 


Here, the class Point has two members that are methods with the same name, move. The 
overloaded move method of class Point chosen for any particular method invocation is 
determined at compile time by the overloading resolution procedure given in §15.12. 


In total, the members of the class Point are the float instance variables x and y declared in 
Point, the two declared move methods, the declared toSt ring method, and the members 
that Point inherits from its implicit direct superclass Object (§4.3.2), such as the method 
hashCode. Note that Point does not inherit the toString method of class Object 
because that method is overridden by the declaration of the toString method in class 
Point. 


Example 8.4.9-2. Overloading, Overriding, and Hiding 


class Point { 
int x = 0, y = 0; 
void move(int dx, int dy) { x += dx; y += dy; } 
int color; 
} 
class RealPoint extends Point { 
float x = 0.0f, y = 0.0f; 
void move(int dx, int dy) { move((float)dx, (float)dy); } 
void move(float dx, float dy) { x += dx; y += dy; } 
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Here, the class RealPoint hides the declarations of the int instance variables x and y of 
class Point with its own float instance variables x and y, and overrides the method move 
of class Point with its own move method. It also overloads the name move with another 
method with a different signature (§8.4.2). 


In this example, the members of the class RealPoint include the instance variable 
color inherited from the class Point, the float instance variables x and y declared in 
RealPoint, and the two move methods declared in RealPoint. 


Which of these overloaded move methods of class RealPoint will be chosen for any 
particular method invocation will be determined at compile time by the overloading 
resolution procedure described in §15.12. 


This following program is an extended variation of the preceding program: 


class Point { 


int x = 0, y = 0, color; 
void move(int dx, int dy) { x += dx; y += dy; } 
int getX() { return x; } 


int getY() { return y; } 
} 
class RealPoint extends Point { 
float x = 0.0f, y = 0.0f; 
void move(int dx, int dy) { move((float)dx, (float)dy); } 
void move(float dx, float dy) { x += dx; y += dy; } 
float getX() { return x; } 
float getY() { return y; } 


Here, the class Point provides methods get X and gety that return the values of its fields 
x and y; the class RealPoint then overrides these methods by declaring methods with the 
same signature. The result is two errors at compile time, one for each method, because the 
return types do not match; the methods in class Point return values of type int, but the 
wanna-be overriding methods in class RealPoint return values of type float. 


This program corrects the errors of the preceding program: 


class Point { 
int x = 0, y = 0; 
void move(int dx, int dy) { x += dx; y += dy; } 
int getX() { return x; } 
int getY() { return y; } 
int color; 
} 
class RealPoint extends Point { 
float x = 0.0f, y = 0.0f; 
void move(int dx, int dy) { move((float)dx, (float)dy); } 
void move(float dx, float dy) { x += dx; y += dy; } 
int getX() { return (int)Math.floor(x); } 
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int getY() { return (int)Math.floor(y); } 


Here, the overriding methods get x and gety in class RealPoint have the same return 
types as the methods of class Point that they override, so this code can be successfully 
compiled. 


Consider, then, this test program: 


class Test { 
public static void main(String[] args) { 
RealPoint rp = new RealPoint(); 
Point p = rp; 
rp.move(1.71828f, 4.14159f); 
p-move(l, -1); 
show(p.x, p.y); 
show(rp.x, rp.y); 
show(p.getX(), p.getY()); 
show(rp.getX(), rp.getY()); 
} 
static void show(int x, int y) { 
Systen.cut.prinkint’(” + eo 8 oe eect Ps 
} 
static void show(float x, float y) { 
System,outsprintin("(" + « + U), 7 Fat 73 


The output from this program is: 


(0, 0) 

(2.7182798, 3.14159) 

(2, 3) 

(2, 3) 

The first line of output illustrates the fact that an instance of RealPoint actually contains 
the two integer fields declared in class Point; it is just that their names are hidden from 
code that occurs within the declaration of class RealPoint (and those of any subclasses 
it might have). When a reference to an instance of class RealPoint in a variable of type 
Point is used to access the field x, the integer field x declared in class Point is accessed. 
The fact that its value is zero indicates that the method invocation p.move (1, -1) did not 
invoke the method move of class Point; instead, it invoked the overriding method move 
of class RealPoint. 


The second line of output shows that the field access rp. x refers to the field x declared in 
class RealPoint. This field is of type float, and this second line of output accordingly 
displays floating-point values. Incidentally, this also illustrates the fact that the method 
name show is overloaded; the types of the arguments in the method invocation dictate which 
of the two definitions will be invoked. 


270 


CLASSES Member Type Declarations 


The last two lines of output show that the method invocations p.getX() and rp. getX () 
each invoke the get xX method declared in class RealPoint. Indeed, there is no way to 
invoke the get x method of class Point for an instance of class RealPoint from outside 
the body of RealPoint, no matter what the type of the variable we may use to hold the 
reference to the object. Thus, we see that fields and methods behave differently: hiding is 
different from overriding. 


8.5 Member Type Declarations 


A member class is a class whose declaration is directly enclosed in the body of 
another class or interface declaration (§8.1.6, §9.1.4). 


A member interface is an interface whose declaration is directly enclosed in the 
body of another class or interface declaration (§8.1.6, §9.1.4). 


The accessibility of a member type declaration in a class is specified by its access 
modifier, or by §6.6 if lacking an access modifier. 


It is a compile-time error if the same keyword appears more than once as a modifier 
for a member type declaration in a class, or if a member type declaration has more 
than one of the access modifiers public, protected, and private (§6.6.) 


The scope and shadowing of a member type is specified in §6.3 and §6.4. 


If a class declares a member type with a certain name, then the declaration of that 
type is said to hide any and all accessible declarations of member types with the 
same name in superclasses and superinterfaces of the class. 


In this respect, hiding of member types is similar to hiding of fields ($8.3). 


A class inherits from its direct superclass and direct superinterfaces all the 
non-private member types of the superclass and superinterfaces that are both 
accessible to code in the class and not hidden by a declaration in the class. 


It is possible for a class to inherit more than one member type with the same name, 
either from its superclass and superinterfaces or from its superinterfaces alone. 
Such a situation does not in itself cause a compile-time error. However, any attempt 
within the body of the class to refer to any such member type by its simple name 
will result in a compile-time error, because the reference is ambiguous. 


There might be several paths by which the same member type declaration is 
inherited from an interface. In such a situation, the member type is considered to be 
inherited only once, and it may be referred to by its simple name without ambiguity. 
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8.5.1 Static Member Type Declarations 


The static keyword may modify the declaration of a member type c within the 
body of a non-inner class or interface T. Its effect is to declare that cis not an inner 
class. Just as a static method of r has no current instance of rin its body, c also 
has no current instance of 7, nor does it have any lexically enclosing instances. 


It is a compile-time error if a static class contains a usage of a non-static 
member of an enclosing class. 


A member interface is implicitly static (§9.1.1). It is permitted for the declaration 
of a member interface to redundantly specify the static modifier. 


8.6 Instance Initializers 


An instance initializer declared in a class is executed when an instance of the class 
is created (§12.5, §15.9, §8.8.7.1). 


Instancelnitializer: 
Block 


It is a compile-time error if an instance initializer cannot complete normally 
($14.21). 


It is a compile-time error if a return statement ($14.17) appears anywhere within 
an instance initializer. 


An instance initializer is permitted to refer to the current object using the keyword 
this (§15.8.3) or the keyword super (§15.11.2, §15.12), and to use any type 
variables in scope. 


Restrictions on how an instance initializer may refer to instance variables, even 
when the instance variables are in scope, are specified in §8.3.3). 


Exception checking for an instance initializer is specified in §11.2.3. 


8.7 Static Initializers 


A static initializer declared in a class is executed when the class is initialized 
(§12.4.2). Together with any field initializers for class variables (§8.3.2), static 
initializers may be used to initialize the class variables of the class. 
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StaticInitializer: 
static Block 


It is a compile-time error if a static initializer cannot complete normally ($14.21). 


It is a compile-time error if a return statement ($14.17) appears anywhere within 
a Static initializer. 


It is a compile-time error if the keyword this (§15.8.3) or the keyword super 
($15.11, §15.12) or any type variable declared outside the static initializer, appears 
anywhere within a static initializer. 


Restrictions on how a static initializer may refer to class variables, even when the 
class variables are in scope, are specified in §8.3.3. 


Exception checking for a static initializer is specified in §11.2.3. 


8.8 Constructor Declarations 


A constructor is used in the creation of an object that is an instance of a class 
($12.5, §15.9). 


ConstructorDeclaration: 
{ConstructorModifier} ConstructorDeclarator [Throws] ConstructorBody 


ConstructorDeclarator: 
[TypeParameters ] SimpleTypeName 
( [ReceiverParameter , ] [FormalParameterList] ) 


SimpleTypeName: 
Typeldentifier 


The rules in this section apply to constructors in all class declarations, including 
enum declarations. However, special rules apply to enum declarations with regard 
to constructor modifiers, constructor bodies, and default constructors; these rules 
are stated in §8.9.2. 


The SimpleTypeName in the ConstructorDeclarator must be the simple name of 
the class that contains the constructor declaration, or a compile-time error occurs. 


In all other respects, a constructor declaration looks just like a method declaration 
that has no result (§8.4.5). 
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Constructor declarations are not members. They are never inherited and therefore 


are not subject to hiding or overriding. 


Constructors are invoked by class instance creation expressions (§15.9), by 
the conversions and concatenations caused by the string concatenation operator 
+ (§15.18.1), and by explicit constructor invocations from other constructors 
(§8.8.7). Access to constructors is governed by access modifiers (§6.6), so it is 
possible to prevent class instantiation by declaring an inaccessible constructor 


($8.8.10). 


Constructors are never invoked by method invocation expressions ($15.12). 


Example 8.8-1. Constructor Declarations 


class Point { 
Int x Oy; 
Point (int x, int y) { this.x = x; this.y = y; } 


8.8.1 Formal Parameters 


The formal parameters of a constructor are identical in syntax and semantics to 


those of a method (§8.4.1). 


The constructor of a non-private inner member class implicitly declares, as the 
first formal parameter, a variable representing the immediately enclosing instance 


of the class (§15.9.2, §15.9.3). 


The rationale for why only this kind of class has an implicitly declared constructor 
parameter is subtle. The following explanation may be helpful: 


1. 


In aclass instance creation expression for a non-private inner member class, §15.9.2 
specifies the immediately enclosing instance of the member class. The member class 
may have been emitted by a compiler which is different than the compiler of the class 
instance creation expression. Therefore, there must be a standard way for the compiler 
of the creation expression to pass a reference (representing the immediately enclosing 
instance) to the member class's constructor. Consequently, the Java programming 
language deems in this section that a non-private inner member class's constructor 
implicitly declares an initial parameter for the immediately enclosing instance. §15.9.3 
specifies that the instance is passed to the constructor. 


In a class instance creation expression for a local class (not in a static context) or 
anonymous class, §15.9.2 specifies the immediately enclosing instance of the local/ 
anonymous class. The local/anonymous class is necessarily emitted by the same 
compiler as the class instance creation expression. That compiler can represent the 
immediately enclosing instance how ever it wishes. There is no need for the Java 
programming language to implicitly declare a parameter in the local/anonymous 
class's constructor. 


CLASSES 


CLASSES Constructor Declarations 


3. In a class instance creation expression for an anonymous class, and where the 
anonymous class's superclass is either inner or local (not in a static context), §15.9.2 
specifies the anonymous class's immediately enclosing instance with respect to 
the superclass. This instance must be transmitted from the anonymous class to its 
superclass, where it will serve as the immediately enclosing instance. Since the 
superclass may have been emitted by a compiler which is different than the compiler 
of the class instance creation expression, it is necessary to transmit the instance in a 
standard way, by passing it as the first argument to the superclass's constructor. Note 
that the anonymous class itself is necessarily emitted by the same compiler as the class 
instance creation expression, so it would be possible for the compiler to transmit the 
immediately enclosing instance with respect to the superclass to the anonymous class 
how ever it wishes, before the anonymous class passes the instance to the superclass's 
constructor. However, for consistency, the Java programming language deems in 
§15.9.5.1 that, in some circumstances, an anonymous class's constructor implicitly 
declares an initial parameter for the immediately enclosing instance with respect to 
the superclass. 


The fact that a non-private inner member class may be accessed by a different compiler 
than compiled it, whereas a local or anonymous class is always accessed by the same 
compiler that compiled it, explains why the binary name of a non-private inner member 
class is defined to be predictable but the binary name of a local or anonymous class is not 


($13.1). 


8.8.2 Constructor Signature 


It is a compile-time error to declare two constructors with override-equivalent 
signatures (§8.4.2) in a class. 


It is a compile-time error to declare two constructors whose signatures have the 
same erasure (§4.6) in a class. 


8.8.3 Constructor Modifiers 


ConstructorModifier: 


(one of) 


Annotation public protected private 


The rules for annotation modifiers on a constructor declaration are specified in 
§9.7.4 and §9.7.5. 


It is a compile-time error if the same keyword appears more than once as a modifier 
in aconstructor declaration, or if a constructor declaration has more than one of the 
access modifiers public, protected, and private (§6.6). 


In a normal class declaration, a constructor declaration with no access modifiers 
has package access. 
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If two or more (distinct) method modifiers appear in a method declaration, it is customary, 
though not required, that they appear in the order consistent with that shown above in the 
production for MethodModifier. 


Unlike methods, a constructor cannot be abstract, static, final, native, strictfp, 
or synchronized: 


¢ A constructor is not inherited, so there is no need to declare it final. 
e An abstract constructor could never be implemented. 


¢ A constructor is always invoked with respect to an object, so it makes no sense for a 
constructor to be static. 


¢ There is no practical need for a constructor to be synchronized, because it would lock 
the object under construction, which is normally not made available to other threads until 
all constructors for the object have completed their work. 


¢ The lack of nat ive constructors is an arbitrary language design choice that makes it easy 
for an implementation of the Java Virtual Machine to verify that superclass constructors 
are always properly invoked during object creation. 


¢ The inability to declare a constructor as strict fp (in contrast to a method (§8.4.3)) 
is an intentional language design choice; it effectively ensures that a constructor is FP- 
strict if and only if its class is FP-strict (§15.4). 


8.8.4 Generic Constructors 


A constructor is generic if it declares one or more type variables ($4.4). 


These type variables are known as the type parameters of the constructor. The 
form of the type parameter section of a generic constructor is identical to the type 
parameter section of a generic class (§8.1.2). 


It is possible for a constructor to be generic independently of whether the class the 
constructor is declared in is itself generic. 


A generic constructor declaration defines a set of constructors, one for each 
possible invocation of the type parameter section by type arguments. Type 
arguments may not need to be provided explicitly when a generic constructor is 
invoked, as they can often by inferred ($18 (Type Inference)). 


The scope and shadowing of a constructor's type parameter is specified in §6.3 and 
§6.4. 


8.8.5 Constructor Throws 


The throws clause for a constructor is identical in structure and behavior to the 
throws Clause for a method (§8.4.6). 
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8.8.6 The Type of a Constructor 


The type of a constructor consists of its signature and the exception types given 
by its throws clause. 


8.8.7 Constructor Body 


The first statement of a constructor body may be an explicit invocation of another 
constructor of the same class or of the direct superclass (§8.8.7.1). 


ConstructorBody: 
{ [ExplicitConstructorInvocation] [BlockStatements] } 


It is a compile-time error for a constructor to directly or indirectly invoke itself 
through a series of one or more explicit constructor invocations involving this. 


If a constructor body does not begin with an explicit constructor invocation and 
the constructor being declared is not part of the primordial class object, then 
the constructor body implicitly begins with a superclass constructor invocation 
"super ();", an invocation of the constructor of its direct superclass that takes no 
arguments. 


Except for the possibility of explicit constructor invocations, and the prohibition 
on explicitly returning a value ($14.17), the body of a constructor is like the body 
of a method (§8.4.7). 


A return statement ($14.17) may be used in the body of a constructor if it does 
not include an expression. 


Example 8.8.7-1. Constructor Bodies 


class Point { 
int x, y; 
Point (int x, int y) { this.x = x; this.y = y; } 
} 
class ColoredPoint extends Point { 
static final int WHITE = 0, BLACK = 1; 
int color; 
ColoredPoint (int x, int y) { 
this(x, y, WHITE); 
} 
ColoredPoint (int x, int y, int color) { 
super(x, y); 


this.color color; 
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Here, the first constructor of ColoredPoint invokes the second, providing an additional 
argument; the second constructor of ColoredPoint invokes the constructor of its 
superclass Point, passing along the coordinates. 


8.8.7.1 Explicit Constructor Invocations 


ExplicitConstructorInvocation: 
[TypeArguments] this ( [ArgumentList] ) ; 
[TypeArguments] super ( [ArgumentList] ) ; 
ExpressionName . [TypeArguments] super ( [ArgumentList] ) ; 
Primary . [TypeArguments] super ( [ArgumentList] ) ; 


The following productions from §4.5.1 and §15.12 are shown here for convenience: 


TypeArguments: 
< TypeArgumentList > 


ArgumentList: 
Expression {, Expression} 


Explicit constructor invocation statements are divided into two kinds: 


¢ Alternate constructor invocations begin with the keyword this (possibly 
prefaced with explicit type arguments). They are used to invoke an alternate 
constructor of the same class. 


¢ Superclass constructor invocations begin with either the keyword super 
(possibly prefaced with explicit type arguments) or a Primary expression or an 
ExpressionName. They are used to invoke a constructor of the direct superclass. 
They are further divided: 


— Unqualified superclass constructor invocations begin with the keyword super 
(possibly prefaced with explicit type arguments). 


— Qualified superclass constructor invocations begin with a Primary expression 
or an ExpressionName. They allow a subclass constructor to explicitly specify 
the newly created object's immediately enclosing instance with respect to the 
direct superclass (§8.1.3). This may be necessary when the superclass is an 
inner class. 


An explicit constructor invocation statement in a constructor body may not refer 
to any instance variables or instance methods or inner classes declared in this class 
or any superclass, or use this Or super in any expression; otherwise, a compile- 
time error occurs. 
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This prohibition on using the current instance explains why an explicit constructor 
invocation statement is deemed to occur in a static context (§8.1.3). 


If TypeArguments is present to the left of this or super, then it is a compile-time 
error if any of the type arguments are wildcards (§4.5.1). 

Let c be the class being instantiated, and let s be the direct superclass of c. 

If a superclass constructor invocation statement is unqualified, then: 


¢ If sis an inner member class, but s is not a member of a class enclosing c, then 
a compile-time error occurs. 


If a superclass constructor invocation statement is qualified, then: 


e If sis not an inner class, or if the declaration of s occurs in a static context, then 
a compile-time error occurs. 


¢ Otherwise, let p be the Primary expression or the ExpressionName immediately 
preceding ".super", and let o be the immediately enclosing class of s. It is a 
compile-time error if the type of p is not o or a subclass of o, or if the type of 
p is not accessible ($6.6). 


The exception types that an explicit constructor invocation statement can throw are 
specified in §11.2.2. 


Evaluation of an alternate constructor invocation statement proceeds by first 
evaluating the arguments to the constructor, left-to-right, as in an ordinary method 
invocation; and then invoking the constructor. 


Evaluation of a superclass constructor invocation statement proceeds as follows: 


1. Let i be the instance being created. The immediately enclosing instance of i 
with respect to s (if any) must be determined: 


e If sis not an inner class, or if the declaration of s occurs in a static context, 
then no immediately enclosing instance of i with respect to s exists. 


¢ If the superclass constructor invocation is unqualified, then s is necessarily 
a local class or an inner member class. 


If sis a local class, then let o be the immediately enclosing type declaration 
of s. 


If sis an inner member class, then let o be the innermost enclosing class of 
c of which s is a member. 


Let n be an integer (n = 1) such that o is the n'th lexically enclosing type 
declaration of c. 
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The immediately enclosing instance of i with respect to s is the n'th lexically 
enclosing instance of this. 


While it may be the case that s is a member of c due to inheritance, the zeroth 
lexically enclosing instance of this (that is, this itself) is never used as the 
immediately enclosing instance of i with respect to S. 


e If the superclass constructor invocation is qualified, then the Primary 
expression or the ExpressionName immediately preceding ". super", p, is 
evaluated. 


If pevaluates to null, aNu11PointerException is raised, and the superclass 
constructor invocation completes abruptly. 


Otherwise, the result of this evaluation is the immediately enclosing instance 
of i with respect to s. 


After determining the immediately enclosing instance of i with respect to s (if 
any), evaluation of the superclass constructor invocation statement proceeds 
by evaluating the arguments to the constructor, left-to-right, as in an ordinary 
method invocation; and then invoking the constructor. 


Finally, if the superclass constructor invocation statement completes normally, 
then all instance variable initializers of c and all instance initializers of c are 
executed. If an instance initializer or instance variable initializer z textually 
precedes another instance initializer or instance variable initializer J, then I is 
executed before v. 


Execution of instance variable initializers and instance initializers is performed 
regardless of whether the superclass constructor invocation actually appears 
as an explicit constructor invocation statement or is provided implicitly. (An 
alternate constructor invocation does not perform this additional implicit 
execution.) 


Example 8.8.7.1-1. Restrictions on Explicit Constructor Invocation Statements 


If the first constructor of ColoredPoint in the example from §8.8.7 were changed as 
follows: 


class Point { 

dint) “Xp: v7 

Point (int x, int y) { this.x = x; this.y = y; } 
} 
class ColoredPoint extends Point { 

static final int WHITE = 0, BLACK = 1; 

int color; 

ColoredPoint (int x, int y) { 
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this(x, y, color); // Changed to color from WHITE 
} 
ColoredPoint (int x, int y, int color) { 

super(x, y); 


this.color color; 


then a compile-time error would occur, because the instance variable color cannot be used 
by a explicit constructor invocation statement. 


Example 8.8.7.1-2. Qualified Superclass Constructor Invocation 


In the code below, ChildOfInner has no lexically enclosing type declaration, so 
an instance of ChildOfInner has no enclosing instance. However, the superclass of 
ChildOfInner (Inner) has a lexically enclosing type declaration (Outer), and an 
instance of Inner must have an enclosing instance of Outer. The enclosing instance of 
Outer is set when an instance of Inner is created. Therefore, when we create an instance of 
ChildOfInner, which is implicitly an instance of Inner, we must provide the enclosing 
instance of Outer via a qualified superclass invocation statement in ChildOfInner's 
constructor. The instance of Outer is called the immediately enclosing instance of 
ChildOfInner with respect to Inner. 


class Outer { 
class Inner {} 

} 

class ChildOfInner extends Outer.Inner { 
ChildOfInner() { (new Outer()).super(); } 


Perhaps surprisingly, the same instance of Outer may serve as the immediately enclosing 
instance of ChildOfInner with respect to Inner for multiple instances of ChildOf Inner. 
These instances of ChildOfInner are implicitly linked to the same instance of Outer. 
The program below achieves this by passing an instance of Outer to the constructor of 
ChildOfInner, which uses the instance in a qualified superclass constructor invocation 
statement. The rules for an explicit constructor invocation statement do not prohibit using 
formal parameters of the constructor that contains the statement. 


class Outer { 


int secret = 5; 

class Inner { 
int getSecret () { return secret; } 
void setSecret(int s) { secret = s; } 


} 
class ChildOfInner extends Outer.Inner { 
ChildOfInner(Outer x) { x.super(); } 


public class Test { 
public static void main(String[] args) { 
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} 


Outer x = new Outer(); 


ChildOfInner a = new 
ChildOfInner b = new 
System.out.printin(b 
a.setSecret (6); 

System.out.printin(b 


This program produces the output: 


5: 
6 


ChildOfInner (x) ; 
ChildOfInner (x) ; 
-getSecret ()); 


-getSecret ()); 
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The effect is that manipulation of instance variables in the common instance of Outer 
is visible through references to different instances of ChildOfInner, even though such 
references are not aliases in the conventional sense. 


8.8.8 Constructor Overloading 


Overloading of constructors is identical in behavior to overloading of methods 
($8.4.9). The overloading is resolved at compile time by each class instance 


creation expression (§15.9). 


8.8.9 Default Constructor 


If a class contains no constructor declarations, then a default constructor is 
implicitly declared. The form of the default constructor for a top level class, 
member class, or local class is as follows: 


¢ The default constructor has the same access modifier as the class, unless the 
class lacks an access modifier, in which case the default constructor has package 


access (§6.6). 


¢ The default constructor has no formal parameters, except in a non-private 
inner member class, where the default constructor implicitly declares one formal 
parameter representing the immediately enclosing instance of the class (§8.8.1, 


§15.9.2, §15.9.3). 


¢ The default constructor has no throws clauses. 


e If the class being declared is the primordial class object, then the default 
constructor has an empty body. Otherwise, the default constructor simply 
invokes the superclass constructor with no arguments. 


The form of the default constructor for an anonymous class is specified in §15.9.5.1. 
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It is a compile-time error if a default constructor is implicitly declared but the 
superclass does not have an accessible constructor that takes no arguments and has 
no throws Clause. 


Example 8.8.9-1. Default Constructors 


The declaration: 


public class Point { 
int x, y; 


is equivalent to the declaration: 


public class Point { 
int x, y; 
public Point() { super(); } 


where the default constructor is public because the class Point is public. 
Example 8.8.9-2. Accessibility of Constructors v. Classes 


The rule that the default constructor of a class has the same accessibility as the class itself 
is simple and intuitive. Note, however, that this does not imply that the constructor is 
accessible whenever the class is accessible. Consider: 


package pl; 
public class Outer { 

protected class Inner {} 
} 
package p2; 
class SonOfOuter extends pl.Outer { 

void foo() { 

new Inner(); // compile-time access error 


The default constructor for Inner is protected. However, the constructor is protected 
relative to Inner, while Inner is protected relative to Outer. So, Inner is accessible 
in SonOfOuter, since it is a subclass of Outer. Inner's constructor is not accessible in 
SonOfOuter, because the class SonofoOuter is not a subclass of Inner! Hence, even 
though Inner is accessible, its default constructor is not. 
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8.8.10 Preventing Instantiation of a Class 


A class can be designed to prevent code outside the class declaration from creating 
instances of the class by declaring at least one constructor, to prevent the creation 
of a default constructor, and by declaring all constructors to be private (§6.6.1). 


A public class can likewise prevent the creation of instances outside its package 
by declaring at least one constructor, to prevent creation of a default constructor 
with public access, and by declaring no constructor that is public or protected 
(§$6.6.2). 


Example 8.8.10-1. Preventing Instantiation via Constructor Accessibility 


class ClassOnly { 

private ClassOnly() { } 

static String just = "only the lonely"; 
} 


Here, the class ClassOnly cannot be instantiated, while in the following code: 


package just; 
public class PackageOnly { 
PackageOnly() { } 
String[] justDesserts = { "cheesecake", "ice cream" }; 


} 


the public class PackageOnly can be instantiated only within the package just, in 
which it is declared. This restriction would also apply if the constructor of PackageOnly 
was protected, although in that case, it would be possible for code in other packages to 
instantiate subclasses of PackageOnly. 


8.9 Enum Types 


An enum declaration specifies a new enum type, a special kind of class type. 


EnumDeclaration: 
{ClassModifier} enum Typeldentifier [Superinterfaces] EnumBody 


It is a compile-time error if an enum declaration has the modifier abstract or 
final. 


An enum declaration is implicitly final unless it contains at least one enum 
constant that has a class body (§8.9.1). 


A nested enum type is implicitly static. It is permitted for the declaration of a 
nested enum type to redundantly specify the static modifier. 


CLASSES 


Enum Types 


This implies that it is impossible to declare an enum type in the body of an inner class 
(§8.1.3), because an inner class cannot have st at ic members except for constant variables. 


It is a compile-time error if the same keyword appears more than once as a modifier 


for an enum declaration, or if an enum decl 


aration has more than one of the access 


modifiers public, protected, and private ($6.6). 


The direct superclass of an enum type £ is | 


An enum type has no instances other than 


Enum< E> (§8.1.4). 


those defined by its enum constants. It 


is acompile-time error to attempt to explicitly instantiate an enum type ($15.9.1). 


In addition to the compile-time error, three further mechanisms ensure that no instances of 


an enum type exist beyond those defined by its 


enum constants: 


¢ The final clone method in Enum ensures that enum constants can never be cloned. 


¢ Reflective instantiation of enum types is prohibited. 


¢ Special treatment by the serialization mechanism ensures that duplicate instances are 


never created as a result of deserialization. 


8.9.1 Enum Constants 


The body of an enum declaration may contain enum constants. An enum constant 


defines an instance of the enum type. 


EnumBody: 


{ [EnumConstantList] [, ] [EnumBodyDeclarations] } 


EnumConstantList: 
EnumConstant {, EnumConstant} 


EnumConstant: 


{EnumConstantModifier} Identifier [ ( [ArgumentList] ) ] [ClassBody] 


EnumConstantModifier: 
Annotation 


The following production from §15.12 is shown here for convenience: 


ArgumentList: 
Expression {, Expression} 


The rules for annotation modifiers on an enum constant declaration are specified 


in §9.7.4 and §9.7.5. 
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The /dentifier in a EnumConstant may be used in a name to refer to the enum 
constant. 


The scope and shadowing of an enum constant is specified in $6.3 and §6.4. 


An enum constant may be followed by arguments, which are passed to the 
constructor of the enum when the constant is created during class initialization as 
described later in this section. The constructor to be invoked is chosen using the 
normal rules of overload resolution (§15.12.2). If the arguments are omitted, an 
empty argument list is assumed. 


The optional class body of an enum constant implicitly defines an anonymous class 
declaration (§15.9.5) that extends the immediately enclosing enum type. The class 
body is governed by the usual rules of anonymous classes; in particular it cannot 
contain any constructors. Instance methods declared in these class bodies may be 
invoked outside the enclosing enum type only if they override accessible methods 
in the enclosing enum type (§8.4.8). 


It is a compile-time error for the class body of an enum constant to declare an 
abstract method. 


Because there is only one instance of each enum constant, it is permitted to use the 
== operator in place of the equals method when comparing two object references 
if it is known that at least one of them refers to an enum constant. 


The equals method in Enum is a final method that merely invokes super.equals on 
its argument and returns the result, thus performing an identity comparison. 


8.9.2 Enum Body Declarations 


In addition to enum constants, the body of an enum declaration may contain 
constructor and member declarations as well as instance and static initializers. 


EnumBodyDeclarations: 
; {ClassBodyDeclaration} 


The following productions from §8.1.6 are shown here for convenience: 


ClassBodyDeclaration: 
ClassMemberDeclaration 
Instancelnitializer 
Staticlnitializer 
ConstructorDeclaration 
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ClassMemberDeclaration: 
FieldDeclaration 
MethodDeclaration 
ClassDeclaration 
InterfaceDeclaration 


Any constructor or member declarations in the body of an enum declaration apply 


to the enum type exactly as if they had been present in the body of a normal class 
declaration, unless explicitly stated otherwise. 


It is a compile-time error if a constructor declaration in an enum declaration is 
public Or protected ($6.6). 


It is a compile-time error if a constructor declaration in an enum declaration 
contains a superclass constructor invocation statement (§8.8.7.1). 


It is a compile-time error to refer to a static field of an enum type from a 
constructor, instance initializer, or instance variable initializer of the enum type, 
unless the field is a constant variable (§4.12.4). 


In an enum declaration, a constructor declaration with no access modifiers is 


private. 


In an enum declaration with no constructor declarations, a default constructor is 
implicitly declared. The default constructor is private, has no formal parameters, 
and has no throws clause. 


In practice, a compiler is likely to mirror the Enum type by declaring String and int 
parameters in the default constructor of an enum type. However, these parameters are not 
specified as "implicitly declared" because different compilers do not need to agree on the 
form of the default constructor. Only the compiler of an enum type knows how to instantiate 
the enum constants; other compilers can simply rely on the implicitly declared public 
static fields of the enum type (§8.9.3) without regard for how those fields were initialized. 


It is a compile-time error if an enum declaration z has an abstract method masa 
member, unless £ has at least one enum constant and all of z's enum constants have 
class bodies that provide concrete implementations of m. 


It is acompile-time error for an enum declaration to declare a finalizer (§12.6). An 
instance of an enum type may never be finalized. 
Example 8.9.2-1. Enum Body Declarations 
enum Coin { 
PENNY (1), NICKEL(5), DIME(10), QUARTER(25); 


Coin(int value) { this.value = value; } 


private final int value; 
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public int value() { return value; } 


Each enum constant arranges for a different value in the field value, passed in via a 
constructor. The field represents the value, in cents, of an American coin. Note that there 
are no restrictions on the parameters that may be declared by an enum type's constructor. 


Example 8.9.2-2. Restriction On Enum Constant Self-Reference 


Without the rule on static field access, apparently reasonable code would fail at run time 
due to the initialization circularity inherent in enum types. (A circularity exists in any class 
with a "self-typed" static field.) Here is an example of the sort of code that would fail: 


import java.util.Map; 
import java.util.HashMap; 


enum Color { 
RED, GREEN, BLUE; 
Color() { colorMap.put (toString(), this); } 


static final Map<String,Color> colorMap = 
new HashMap<String,Color>(); 


Static initialization of this enum would throw a NullPointerException because the 
static variable colorMap is uninitialized when the constructors for the enum constants 
run. The restriction above ensures that such code cannot be compiled. However, the code 
can easily be refactored to work properly: 


import java.util.Map; 
import java.util.HashMap; 


enum Color { 
RED, GREEN, BLUE; 


static final Map<String,Color> colorMap = 
new HashMap<String,Color>(); 
static { 


for (Color c : Color.values() ) 
colorMap.put(c.toString(), c); 


The refactored version is clearly correct, as static initialization occurs top to bottom. 


8.9.3. Enum Members 


The members of an enum type £ are all of the following: 


¢ Members declared in the body of the declaration of E. 
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¢ Members inherited from Enum<E>. 


¢ For each enum constant c declared in the body of the declaration of £, = has 
an implicitly declared public static final field of type = that has the same 
name as c. The field has a variable initializer which instantiates £ and passes any 
arguments of c to the constructor chosen for £. The field has the same annotations 
as c (if any). 


These fields are implicitly declared in the same order as the corresponding 
enum constants, before any static fields explicitly declared in the body of the 
declaration of £. 


An enum constant is said to be created when the corresponding implicitly 
declared field is initialized. 


¢ The following implicitly declared methods: 


[** 


+ + + F F F F OF 


* 


Returns an array containing the constants of this enum 
type, in the order they're declared. This method may be 
used to iterate over the constants as follows: 


for(E c : E.values()) 
System.out.printin(c); 


@return an array containing the constants of this enum 
type, in the order they're declared 


*/ 

public static E[] values(); 

[** 

* Returns the enum constant of this type with the specified 
* name. 

* The string must match exactly an identifier used to declare 
* an enum constant in this type. (Extraneous whitespace 

* characters are not permitted.) 

* 

* @return the enum constant with the specified name 

* 


* 


*/: 


@throws IllegalArgumentException if this enum type has no 
constant with the specified name 


public static E valueOf (String name); 


It follows that the declaration of enum type £ cannot contain fields that conflict with the 
implicitly declared fields corresponding to E's enum constants, nor contain methods that 
conflict with implicitly declared methods or override final methods of class Enum<E>. 


Example 8.9.3-1. Iterating Over Enum Constants With An Enhanced for Loop 


public class Test { 
enum Season { WINTER, SPRING, SUMMER, FALL } 
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public static void main(String[] args) { 
for (Season s : Season.values() ) 
System.out.printin(s); 


This program produces the output: 


WINTER 
SPRING 
SUMMER 
FALL 


Example 8.9.3-2. Switching Over Enum Constants 


A switch statement ($14.11) is useful for simulating the addition of a method to an enum 
type from outside the type. This example "adds" a color method to the Coin type from 
§8.9.2, and prints a table of coins, their values, and their colors. 


class Test { 
enum CoinColor { COPPER, NICKEL, SILVER } 


static CoinColor color(Coin c) { 
switch (c) { 
case PENNY: 
return CoinColor.COPPER; 
case NICKEL: 
return CoinColor.NICKEL; 
case DIME: case QUARTER: 
return CoinColor.SILVER; 
default: 
throw new AssertionError ("Unknown coin: " + c); 


public static void main(String[] args) { 
for (Coin c : Coin.values() ) 
System.out.printin(c + "\t\t" + 
c.value() + "\t" + color(c)); 


This program produces the output: 


PENNY 1 COPPER 
NICKEL cS) NICKEL 
DIME 10 SILVER 
QUARTER 25 SILVER 
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Example 8.9.3-3. Enum Constants with Class Bodies 


enum Operation { 


PLUS { 
double eval(double x, double y) return x + y; 
r 
MINUS { 
double eval(double x, double y) return x - y; 
, 
TIMES { 
double eval(double x, double y) return x * y; 
, 
DIVIDED_BY { 
double eval(double x, double y) return x / y; 


// Bach constant supports an arithmetic operation 
abstract double eval(double x, double y); 


public static void main(String args[]) { 
double x = Double.parseDouble(args[0]); 
double y = Double.parseDouble(args[1]); 
for (Operation op : Operation.values() ) 
System.out.println(x + " "+ op +" "+y+Ht 
"= " + op.eval(x, y)); 


Class bodies attach behaviors to the enum constants. The program produces the output: 


java Operation 2.0 4.0 
2.0 PLUS 4.0 = 6.0 

2.0 MINUS 4.0 = -2.0 

2.0 TIMES 4.0 = 8.0 

2.0 DIVIDED_BY 4.0 = 0.5 


This pattern is much safer than using a switch statement in the base type (Operation), 
as the pattern precludes the possibility of forgetting to add a behavior for a new constant 
(since the enum declaration would cause a compile-time error). 


Example 8.9.3-4. Multiple Enum Types 


In the following program, a playing card class is built atop two simple enums. 


import java.util.List; 
import java.util.ArrayList; 
class Card implements Comparable<Card>, 
java.io.Serializable { 
public enum Rank { DEUCE, THREE, FOUR, FIVE, SIX, SEVEN, 
EIGHT, NINE, TEN, JACK, QUEEN, KING, ACE } 
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public enum Suit { CLUBS, DIAMONDS, HEARTS, SPADES } 


private final Rank rank; 
private final Suit suit; 
public Rank rank() { return rank; } 
public Suit suit() { return suit; } 


private Card(Rank rank, Suit suit) { 
if (rank == null || suit == null) 
throw new NullPointerException(rank + ", " + suit); 
this.rank = rank; 
this.suit = suit; 


public String toString() { return rank + " of " + suit; } 


// Primary sort on suit, secondary sort on rank 
public int compareTo(Card c) { 


int suitCompare = suit.compareTo(c.suit); 
return (suitCompare != 0 ? 
suitCompare : 


rank.compareTo(c.rank) ); 


private static final List<Card> prototypeDeck = 
new ArrayList<Card> (52); 


static { 
for (Suit suit : Suit.values()) 
for (Rank rank : Rank.values() ) 
prototypeDeck.add(new Card(rank, suit)); 


// Returns a new deck 
public static List<Card> newDeck() { 
return new ArrayList<Card> (prototypeDeck) ; 


The following program exercises the Card class. It takes two integer parameters on the 
command line, representing the number of hands to deal and the number of cards in each 


hand: 


import java.util.List; 

import java.util.ArrayList; 
import java.util.Collections; 
class Deal { 


public static void main(String args[]) { 
int numHands = Integer.parselInt (args[0]); 
int cardsPerHand = Integer.parseInt (args[1]); 
List<Card> deck = Card.newDeck(); 


Collections.shuffle (deck) ; 
for (int i=0; i < numHands; i++) 
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System.out.println(dealHand(deck, cardsPerHand) ); 


* Returns a new ArrayList consisting of the last n 
* elements of deck, which are removed from deck. 
* The returned list is sorted using the elements’ 
* natural ordering. 
*/ 
public static <E extends Comparable<E>> 
ArrayList<E> dealHand(List<E> deck, int n) { 
int deckSize = deck.size(); 
List<E> handView = deck.subList (deckSize - n, deckSize); 
ArrayList<E> hand = new ArrayList<E>(handView) ; 
handView.clear(); 
Collections.sort (hand) ; 
return hand; 


The program produces the output: 


java Deal 4 3 

[DEUCE of CLUBS, SEVEN of CLUBS, QUEEN of DIAMONDS] 
[NINE of HEARTS, FIVE of SPADES, ACE of SPADES] 
[THREE of HEARTS, SIX of HEARTS, TEN of SPADES] 
[TEN of CLUBS, NINE of DIAMONDS, THREE of SPADES] 
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AN interface declaration introduces a new reference type whose members are 
classes, interfaces, constants, and methods. This type has no instance variables, and 
typically declares one or more abstract methods; otherwise unrelated classes can 
implement the interface by providing implementations for its abstract methods. 
Interfaces may not be directly instantiated. 


A nested interface is any interface whose declaration occurs within the body of 
another class or interface. 


A top level interface is an interface that is not a nested interface. 


We distinguish between two kinds of interfaces - normal interfaces and annotation 
types. 


This chapter discusses the common semantics of all interfaces - normal interfaces, 
both top level ($7.6) and nested (§8.5, §9.5), and annotation types (§9.6). Details 
that are specific to particular kinds of interfaces are discussed in the sections 
dedicated to these constructs. 


Programs can use interfaces to make it unnecessary for related classes to share a 
common abstract superclass or to add methods to object. 


An interface may be declared to be a direct extension of one or more other 
interfaces, meaning that it inherits all the member types, instance methods, and 
constants of the interfaces it extends, except for any members that it may override 
or hide. 


A class may be declared to directly implement one or more interfaces, meaning 
that any instance of the class implements all the abstract methods specified 
by the interface or interfaces. A class necessarily implements all the interfaces 
that its direct superclasses and direct superinterfaces do. This (multiple) interface 
inheritance allows objects to support (multiple) common behaviors without sharing 
a superclass. 
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A variable whose declared type is an interface type may have as its value a 
reference to any instance of a class which implements the specified interface. It is 
not sufficient that the class happen to implement all the abstract methods of the 
interface; the class or one of its superclasses must actually be declared to implement 
the interface, or else the class is not considered to implement the interface. 


9.1 Interface Declarations 


An interface declaration specifies a new named reference type. There are two 
kinds of interface declarations - normal interface declarations and annotation type 
declarations (§9.6). 


InterfaceDeclaration: 
NormalInterfaceDeclaration 
AnnotationTypeDeclaration 


NormalnterfaceDeclaration: 
{InterfaceModifier} interface Typeldentifier [TypeParameters ] 
[ExtendsInterfaces] InterfaceBody 


The Typeldentifier in an interface declaration specifies the name of the interface. 


It is a compile-time error if an interface has the same simple name as any of its 
enclosing classes or interfaces. 


The scope and shadowing of an interface declaration is specified in §6.3 and §6.4. 


9.1.1 Interface Modifiers 


An interface declaration may include interface modifiers. 


InterfaceModifier: 
(one of) 


Annotation public protected private 


abstract static strictfp 


The rules for annotation modifiers on an interface declaration are specified in §9.7.4 
and §9.7.5. 


The access modifier public (§6.6) pertains to every kind of interface declaration. 


INTERFACES Interface Declarations 9.1 


The access modifiers protected and private pertain only to member interfaces 
whose declarations are directly enclosed by a class declaration (§8.5.1). 


The modifier static pertains only to member interfaces (§8.5.1, $9.5), not to top 
level interfaces (§7.6). 


It is a compile-time error if the same keyword appears more than once as a modifier 
for an interface declaration, or if a interface declaration has more than one of the 
access modifiers public, protected, and private (§6.6). 


If two or more (distinct) interface modifiers appear in an interface declaration, then it is 
customary, though not required, that they appear in the order consistent with that shown 
above in the production for InterfaceModifier. 


9.1.1.1 abstract Interfaces 


Every interface is implicitly abstract. 


This modifier is obsolete and should not be used in new programs. 


9.1.1.2 strictfp Interfaces 


The effect of the strictfp modifier is to make all float or double expressions 
within the interface declaration be explicitly FP-strict ($15.4). 


This implies that all methods declared in the interface, and all nested types declared 
in the interface, are implicitly strict fp. 


9.1.2 Generic Interfaces and Type Parameters 


An interface is generic if it declares one or more type variables (§4.4). 


These type variables are known as the type parameters of the interface. The type 
parameter section follows the interface name and is delimited by angle brackets. 


The following productions from §8.1.2 and §4.4 are shown here for convenience: 


TypeParameters: 
< TypeParameterList > 


TypeParameterList: 
TypeParameter {, TypeParameter} 


TypeParameter: 
{TypeParameterModifier} Typeldentifier [TypeBound] 


TypeParameterModifier: 
Annotation 
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TypeBound: 
extends TypeVariable 
extends ClassOrInterfaceType {AdditionalBound} 


AdditionalBound: 
& InterfaceType 


The rules for annotation modifiers on a type parameter declaration are specified 
in §9.7.4 and 89.7.5. 


In an interface's type parameter section, a type variable 7 directly depends on a 
type variable s if s is the bound of 7, while r depends on s if either r directly 
depends on sor rdirectly depends on a type variable u that depends on s (using this 
definition recursively). It is a compile-time error if a type variable in a interface's 
type parameter section depends on itself. 


The scope and shadowing of an interface's type parameter is specified in §6.3. 


It is a compile-time error to refer to a type parameter of a generic interface z 
anywhere in the declaration of a static member of 1 (§9.3, §9.4, §9.5). 


A generic interface declaration defines a set of parameterized types ($4.5), one for 
each possible parameterization of the type parameter section by type arguments. 
All of these parameterized types share the same interface at run time. 


9.1.3 Superinterfaces and Subinterfaces 


If an extends clause is provided, then the interface being declared extends each 
of the other named interfaces and therefore inherits the member types, instance 
methods, and constants of each of the other named interfaces. 


These other named interfaces are the direct superinterfaces of the interface being 
declared. 


Any class that implements the declared interface is also considered to implement 
all the interfaces that this interface extends. 


ExtendsInterfaces: 
extends InterfaceTypeList 


The following production from §8.1.5 is shown here for convenience: 


InterfaceTypeList: 
InterfaceType {, InterfaceType} 


Each InterfaceType in the extends clause of an interface declaration must name 
an accessible interface type (§6.6), or a compile-time error occurs. 
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If an InterfaceType has type arguments, it must denote a well-formed parameterized 
type (§4.5), and none of the type arguments may be wildcard type arguments, or 
a compile-time error occurs. 


Given a (possibly generic) interface declaration I<Fj,...,F,> (n 2 0), the direct 
superinterfaces of the interface type I<Fyj,...,F,> are the types given in the extends 
clause of the declaration of 1, if an extends clause is present. 


Given a generic interface declaration I<F),...,F,> (n > 0), the direct superinterfaces 
of the parameterized interface type I<Tj,...,T,>, where T; (1 <i <n) is a type, are 
all types J<U; 9,...,u, 09>, where J<Uj,...,U;,> is a direct superinterface of I<Fy,...,Fn> 
and @ is the substitution [F,:=T,,...,Fni=Tnl- 


The superinterface relationship is the transitive closure of the direct superinterface 
relationship. An interface xk is a superinterface of interface r if either of the 
following is true: 


* Kis a direct superinterface of 1. 


e There exists an interface 7 such that x is a superinterface of J, and J is a 
superinterface of z, applying this definition recursively. 


Interface r is said to be a subinterface of interface x whenever x is a superinterface 
of z. 


While every class is an extension of class object, there is no single interface of 
which all interfaces are extensions. 


An interface z directly depends on a type Tif Tis mentioned in the extends clause 
of rz either as a superinterface or as a qualifier in the fully qualified form of a 
superinterface name. 


An interface r depends on a reference type T if any of the following is true: 
¢ rdirectly depends on T. 
¢ rdirectly depends on a class c that depends on r (§8.1.5). 


e zr directly depends on an interface 7 that depends on r (using this definition 
recursively). 


It is a compile-time error if an interface depends on itself. 


If circularly declared interfaces are detected at run time, as interfaces are loaded, 
then a ClassCircularityError is thrown (§12.2.1). 
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9.1.4 Interface Body and Member Declarations 


The body of an interface may declare members of the interface, that is, fields (§9.3), 
methods (§9.4), classes (§9.5), and interfaces (§9.5). 


InterfaceBody: 
{ {InterfaceMemberDeclaration} } 


InterfaceMemberDeclaration: 
ConstantDeclaration 
InterfaceMethodDeclaration 
ClassDeclaration 
InterfaceDeclaration 


’ 


The scope of a declaration of a member m declared in or inherited by an interface 
type I is specified in §6.3. 


9.2 Interface Members 


The members of an interface type are: 
¢« Members declared in the body of the interface (§9.1.4). 
¢ Members inherited from any direct superinterfaces (§9.1.3). 


¢ If an interface has no direct superinterfaces, then the interface implicitly declares 


apublic abstract member method m with signature s, return type r, and throws 
clause t corresponding to each public instance method m with signature s, return 
type r, and throws clause t declared in object (§4.3.2), unless an abstract 
method with the same signature, same return type, and a compatible throws 
clause is explicitly declared by the interface. 


It is a compile-time error if the interface explicitly declares such a method m in 
the case where m is declared to be final in Object. 


It is a compile-time error if the interface explicitly declares a method with a 
signature that is override-equivalent (§8.4.2) to a public method of object, but 
which has a different return type, or an incompatible throws clause, or is not 


abstract. 


The interface inherits, from the interfaces it extends, all members of those 
interfaces, except for (i) fields, classes, and interfaces that it hides, (ii) abstract 
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methods and default methods that it overrides (§9.4.1), (i1i) private methods, and 
(iv) static methods. 


Fields, methods, and member types of an interface type may have the same name, 
since they are used in different contexts and are disambiguated by different lookup 
procedures (§6.5). However, this is discouraged as a matter of style. 


9.3 Field (Constant) Declarations 


ConstantDeclaration: 
{ConstantModifier} UnannType VariableDeclaratorList ; 


ConstantModifier: 
(one of) 
Annotation public 


static final 


See §8.3 for UnannType. The following productions from §4.3 and §8.3 are shown here 
for convenience: 


VariableDeclaratorList: 
VariableDeclarator {, VariableDeclarator} 


VariableDeclarator: 
VariableDeclaratorld [= Variablelnitializer] 


VariableDeclaratorld: 
Identifier [Dims] 


Dims: 
{Annotation} [| ] {{Annotation} [ ]} 


VariableInitializer: 
Expression 
Arraylnitializer 


The rules for annotation modifiers on an interface field declaration are specified 
in §9.7.4 and 89.7.5. 


Every field declaration in the body of an interface is implicitly public, static, 
and final. It is permitted to redundantly specify any or all of these modifiers for 
such fields. 


It is a compile-time error if the same keyword appears more than once as a modifier 
for a field declaration. 
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If two or more (distinct) field modifiers appear in a field declaration, it is customary, though 
not required, that they appear in the order consistent with that shown above in the production 
for ConstantModifier. 


The declared type of a field is denoted by UnannType if no bracket pairs appear in 
UnannType and VariableDeclaratorld, and is specified by §10.2 otherwise. 


The scope and shadowing of an interface field declaration is specified in §6.3 and 
$6.4. 


It is a compile-time error for the body of an interface declaration to declare two 
fields with the same name. 


If the interface declares a field with a certain name, then the declaration of that field 
is said to hide any and all accessible declarations of fields with the same name in 
superinterfaces of the interface. 


It is possible for an interface to inherit more than one field with the same name. 
Such a situation does not in itself cause a compile-time error. However, any attempt 
within the body of the interface to refer to any such field by its simple name will 
result in a compile-time error, because the reference is ambiguous. 


There might be several paths by which the same field declaration is inherited from 
an interface. In such a situation, the field is considered to be inherited only once, 
and it may be referred to by its simple name without ambiguity. 


Example 9.3-1. Ambiguous Inherited Fields 


If two fields with the same name are inherited by an interface because, for example, two 
of its direct superinterfaces declare fields with that name, then a single ambiguous member 
results. Any use of this ambiguous member will result in a compile-time error. In the 
program: 


interface BaseColors { 
int RED = 1, GREEN = 2, BLUE = 4; 


interface RainbowColors extends BaseColors { 
int YELLOW = 3, ORANGE = 5, INDIGO = 6, VIOLET = 7; 


interface PrintColors extends BaseColors { 
int YELLOW = 8, CYAN = 16, MAGENTA = 32; 


interface LotsOfColors extends RainbowColors, PrintColors { 
int FUCHSIA = 17, VERMILION = 43, CHARTREUSE = RED+90; 


the interface Lot sOfColors inherits two fields named YELLOw. This is all right as long as 
the interface does not contain any reference by simple name to the field YELLOw. (Such a 
reference could occur within a variable initializer for a field.) 
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Even if interface PrintColors were to give the value 3 to YELLOW rather than the value 
8, areference to field YELLOW within interface Lot sOfColors would still be considered 
ambiguous. 


Example 9.3-2. Multiply Inherited Fields 


If a single field is inherited multiple times from the same interface because, for example, 
both this interface and one of this interface's direct superinterfaces extend the interface that 
declares the field, then only a single member results. This situation does not in itself cause 
a compile-time error. 


In the previous example, the fields RED, GREEN, and BLUE are inherited by interface 
Lot sOfColors in more than one way, through interface RainbowColors and also through 
interface PrintColors, but the reference to field RED in interface Lot sOfColors is not 
considered ambiguous because only one actual declaration of the field RED is involved. 


9.3.1 Initialization of Fields in Interfaces 


Every declarator in a field declaration of an interface must have a variable 
initializer, or a compile-time error occurs. 


The initializer need not be a constant expression (§15.28). 


It is a compile-time error if the initializer of an interface field uses the simple name 
of the same field or another field whose declaration occurs textually later in the 
same interface. 


It is a compile-time error if the keyword this (§15.8.3) or the keyword super 
(§15.11.2, §15.12) occurs in the initializer of an interface field, unless the 
occurrence is within the body of an anonymous class (§15.9.5). 


At run time, the initializer is evaluated and the field assignment performed exactly 
once, when the interface is initialized (§12.4.2). 


Note that interface fields that are constant variables (§4.12.4) are initialized before 
other interface fields. This also applies to static fields that are constant variables 
in classes (§8.3.2). Such fields will never be observed to have their default initial 
values ($4.12.5), even by devious programs. 


Example 9.3.1-1. Forward Reference to a Field 


interface Test { 
float f = j; 
nt j=1; 
int k =k + 1; 


This program causes two compile-time errors, because j is referred to in the initialization 
of £ before 3 is declared, and because the initialization of k refers to k itself. 
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9.4 Method Declarations 


InterfaceMethodDeclaration: 
{InterfaceMethodModifier} MethodHeader MethodBody 


InterfaceMethodModifier: 
(one of) 
Annotation public private 
abstract default static strictfp 


The following productions from §8.4, §8.4.5, and §8.4.7 are shown here for convenience: 


MethodHeader: 
Result MethodDeclarator [Throws] 
TypeParameters {Annotation} Result MethodDeclarator [Throws] 


Result: 
UnannType 
void 


MethodDeclarator: 
Identifier ( [ReceiverParameter , ] [FormalParameterList] ) [Dims] 


MethodBody: 
Block 


’ 


The rules for annotation modifiers on an interface method declaration are specified 
in §9.7.4 and 89.7.5. 


A method in the body of an interface may be declared public or private (§6.6). 
If no access modifier is given, the method is implicitly public. It is permitted, but 
discouraged as a matter of style, to redundantly specify the public modifier for a 
method declaration in an interface. 


A default method is an instance method declared in an interface with the default 
modifier. Its body is always represented by a block, which provides a default 
implementation for any class that implements the interface without overriding the 
method. Default methods are distinct from concrete methods (§8.4.3.1), which 
are declared in classes, and from private interface methods, which are neither 
inherited nor overridden. 


An interface can declare static methods, which are invoked without reference to 
a particular object. static interface methods are distinct from default methods, 
which are instance methods. 


304 


INTERFACES Method Declarations 


It is a compile-time error to use the name of a type parameter of any surrounding 
declaration in the header or body of a static method of an interface. 


The effect of the strictfp modifier is to make all float or double expressions 
within the body of a default or static method be explicitly FP-strict ($15.4). 


An interface method lacking a private, default, or static modifier is implicitly 
abstract. Its body is represented by a semicolon, not a block. It is permitted, but 
discouraged as a matter of style, to redundantly specify the abstract modifier for 
such a method declaration. 


Note that an interface method may not be declared with protected or package access, or 
with the modifiers final, synchronized, or native. 


It is acompile-time error if the same keyword appears more than once as a modifier 
for an interface method declaration, or if an interface method declaration has more 
than one of the access modifiers public and private (§6.6). 


It is a compile-time error if an interface method declaration has more than one of 
the keywords abstract, default, Or static. 


It is a compile-time error if an interface method declaration that contains the 
keyword private also contains the keyword abstract or default. It is permitted 
for an interface method declaration to contain both private and static. 


It is a compile-time error if an interface method declaration that contains the 
keyword abstract also contains the keyword strict fp. 


It is a compile-time error for the body of an interface to declare, explicitly or 
implicitly, two methods with override-equivalent signatures (§8.4.2). However, an 
interface may inherit several abstract methods with such signatures (§9.4.1). 


A method declared in an interface may be generic. The rules for type parameters 
of a generic method in an interface are the same as for a generic method in a class 
($8.4.4). 


9.4.1 Inheritance and Overriding 


An interface r inherits from its direct superinterfaces all abstract and default 
methods m for which all of the following are true: 


* mis a member of a direct superinterface, v, of T. 


¢ No method declared in r has a signature that is a subsignature (§8.4.2) of the 
signature of m. 
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e There exists no method m' that is a member of a direct superinterface, 7, of I (m 
distinct from m’, 7 distinct from ), such that m overrides from J the declaration 
of the method m. 


Note that methods are overridden on a signature-by-signature basis. If, for example, an 
interface declares two public methods with the same name (§9.4.2), and a subinterface 
overrides one of them, the subinterface still inherits the other method. 


The third clause above prevents a subinterface from re-inheriting a method that has already 
been overridden by another of its superinterfaces. For example, in this program: 


interface Top { 
default String name() { return "unnamed"; } 
} 
interface Left extends Top { 
default String name() { return getClass().getName(); } 
} 
interface Right extends Top {} 


interface Bottom extends Left, Right {} 


Right inherits name() from Top, but Bottom inherits name() from Left, not Right. 
This is because name () from Left overrides the declaration of name () in Top. 


An interface does not inherit private or static methods from its superinterfaces. 


If an interface r declares a private or static method m, and the signature of mis a 
subsignature of a public instance method m' in a superinterface of z, and m would 
otherwise be accessible to code in r, then a compile-time error occurs. 


In essence, a static method in an interface cannot hide an instance method in a 
superinterface. This is similar to the rule in §8.4.8.2 whereby a static method in a class 
cannot hide an instance method in a superclass or superinterface. Note that the rule in 
§8.4.8.2 speaks of a class that "declares or inherits a static method", whereas the rule 
above speaks only of an interface that "declares a static method", since an interface 
cannot inherit a static method. Also note that the rule in §8.4.8.2 allows hiding of 
both instance and static methods in superclasses/superinterfaces, whereas the rule above 
considers only public instance methods in superinterfaces. 


Along the same lines, a private method in an interface cannot override an instance method 
- whether public or private - in a superinterface. This is similar to the rules in §8.4.8.1 
and §8.4.8.3 whereby a private method in a class cannot override any instance method in 
a superclass or superinterface, because §8.4.8.1 requires the overridden method to be non- 
private and §8.4.8.3 requires the overriding method to provide at least as much access as 
the overridden method. In summary, only public methods in interfaces can be overridden, 
and only by public methods in subinterfaces or in implementing classes. 
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9.4.1.1 Overriding (by Instance Methods) 


An instance method m; declared in or inherited by interface 1, overrides from 1 
another instance method m, declared in interface y, iff all of the following are true: 


¢ risa subinterface of v. 

¢ zr does not inherit m,. 

¢ The signature of m; is a subsignature ($8.4.2) of the signature of mj. 
* mz is public. 


The presence or absence of the strict fp modifier has absolutely no effect on the 
rules for overriding methods. For example, it is permitted for a method that is not 
FP-strict to override an FP-strict method and it is permitted for an FP-strict method 
to override a method that is not FP-strict. 


An overridden default method can be accessed by using a method invocation expression 
($15.12) that contains the keyword super qualified by a superinterface name. 


9.4.1.2 Requirements in Overriding 


The relationship between the return type of an interface method and the return types 
of any overridden interface methods is specified in §8.4.8.3. 


The relationship between the throws clause of an interface method and the throws 
clauses of any overridden interface methods is specified in §8.4.8.3. 


The relationship between the signature of an interface method and the signatures 
of any overridden interface methods is specified in §8.4.8.3. 


The relationship between the accessibility of an interface method and the 
accessibility of any overridden interface methods is specified in §8.4.8.3. 


It is a compile-time error if a default method is override-equivalent with a non- 
private method of the class object, because any class implementing the interface 
will inherit its own implementation of the method. 


The prohibition against declaring one of the Object methods as a default method may 
be surprising. There are, after all, cases like java.util.List in which the behavior of 
toString and equals are precisely defined. The motivation becomes clearer, however, 
when some broader design decisions are understood: 


¢ First, methods inherited from a superclass are allowed to override methods inherited 
from superinterfaces (§8.4.8.1). So, every implementing class would automatically 
override an interface's toString default. This is longstanding behavior in the Java 
programming language. It is not something we wish to change with the design of 
default methods, because that would conflict with the goal of allowing interfaces to 
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unobtrusively evolve, only providing default behavior when a class doesn't already have 
it through the class hierarchy. 


¢ Second, interfaces do not inherit from Object, but rather implicitly declare many of the 
same methods as Object (§9.2). So, there is no common ancestor for the toString 
declared in Object and the toString declared in an interface. At best, if both were 
candidates for inheritance by a class, they would conflict. Working around this problem 
would require awkward commingling of the class and interface inheritance trees. 


¢ Third, use cases for declaring Object methods in interfaces typically assume a linear 
interface hierarchy; the feature does not generalize very well to multiple inheritance 
scenarios. 


¢ Fourth, the Object methods are so fundamental that it seems dangerous to allow an 
arbitrary superinterface to silently add a default method that changes their behavior. 


An interface is free, however, to define another method that provides behavior useful for 
classes that override the Object methods. For example, the java.util.List interface 
could declare an element String method that produces the string described by the contract 
of toString; implementors of toString in classes could then delegate to this method. 


9.4.1.3 Inheriting Methods with Override-Equivalent Signatures 


It is possible for an interface to inherit several methods with override-equivalent 
signatures (§8.4.2). 


If an interface z inherits a default method whose signature is override-equivalent 
with another method inherited by z, then a compile-time error occurs. (This is the 
case whether the other method is abstract or default.) 


Otherwise, all the inherited methods are abstract, and the interface is considered 
to inherit all the methods. 


One of the inherited methods must be return-type-substitutable for every other 
inherited method, or else a compile-time error occurs. (The throws clauses do not 
cause errors in this case.) 


There might be several paths by which the same method declaration is inherited 
from an interface. This fact causes no difficulty and never, of itself, results in a 
compile-time error. 


Naturally, when two different default methods with matching signatures are inherited by a 
subinterface, there is a behavioral conflict. We actively detect this conflict and notify the 
programmer with an error, rather than waiting for the problem to arise when a concrete 
class is compiled. The error can be avoided by declaring a new method that overrides, and 
thus prevents the inheritance of, all conflicting methods. 


Similarly, when an abstract method and a default method with matching signatures are 
inherited by a subinterface, we produce an error. In this case, it would be possible to give 
priority to one or the other - perhaps we would assume that the default method provides 
a reasonable implementation for the abstract method. But this is risky, since other than 
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the coincidental name and signature, we have no reason to believe that the default method 
behaves consistently with the abstract method's contract - the default method may not have 
even existed when the subinterface was originally developed. It is safer in this situation 
to ask the user to actively assert that the default implementation is appropriate (via an 
overriding declaration). 


In contrast, the longstanding behavior for inherited concrete methods in classes is that they 
override abstract methods declared in interfaces (see §8.4.8). The same argument about 
potential contract violation applies here, but in this case there is an inherent imbalance 
between classes and interfaces. We prefer, in order to preserve the independent nature of 
class hierarchies, to minimize class-interface clashes by simply giving priority to concrete 
methods. 


9.4.2 Overloading 


If two methods of an interface (whether both declared in the same interface, or both 
inherited by an interface, or one declared and one inherited) have the same name 
but different signatures that are not override-equivalent (§8.4.2), then the method 
name is said to be overloaded. 


This fact causes no difficulty and never of itself results in a compile-time error. 
There is no required relationship between the return types or between the throws 
clauses of two methods with the same name but different signatures that are not 
override-equivalent. 


Example 9.4.2-1. Overloading an abst ract Method Declaration 


interface PointInterface { 
void move(int dx, int dy); 

} 

interface RealPointInterface extends PointInterface { 
void move(float dx, float dy); 
void move(double dx, double dy); 

} 


Here, the method named move is overloaded in interface RealPoint Interface with three 
different signatures, two of them declared and one inherited. Any non-abst ract class that 
implements interface RealPoint Interface must provide implementations of all three 
method signatures. 


9.4.3 Interface Method Body 


A default method has a block body. This block of code provides an implementation 
of the method in the event that a class implements the interface but does not provide 
its own implementation of the method. 


A private Or static method also has a block body, which provides the 
implementation of the method. 
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It is a compile-time error if an interface method declaration is abstract (explicitly 
or implicitly) and has a block for its body. 


It is a compile-time error if an interface method declaration is default, private, 
or static, and has a semicolon for its body. 


It is a compile-time error for the body of a static method to attempt to reference 
the current object using the keyword this or the keyword super. 


The rules for return statements in a method body are specified in §14.17. 


If a method is declared to have a return type (§8.4.5), then a compile-time error 
occurs if the body of the method can complete normally (§14.1). 


9.5 Member Type Declarations 


Interfaces may contain member type declarations ($8.5). 


Every member type declaration in the body of an interface is implicitly public and 
static. It is permitted to redundantly specify either or both of these modifiers. 


It is a compile-time error if a member type declaration in an interface has the 
modifier protected or private. 


It is a compile-time error if the same keyword appears more than once as a modifier 
for a member type declaration in an interface. 


If an interface declares a member type with a certain name, then the declaration of 
that type is said to hide any and all accessible declarations of member types with 
the same name in superinterfaces of the interface. 


An interface inherits from its direct superinterfaces all the non-private member 
types of the superinterfaces that are both accessible to code in the interface and not 
hidden by a declaration in the interface. 


It is possible for an interface to inherit more than one member type with the same 
name. Such a situation does not in itself cause a compile-time error. However, 
any attempt within the body of the interface to refer to any such member type 
by its simple name will result in a compile-time error, because the reference is 
ambiguous. 


There might be several paths by which the same member type declaration is 
inherited from an interface. In such a situation, the member type is considered to be 
inherited only once, and it may be referred to by its simple name without ambiguity. 
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9.6 Annotation Types 


An annotation type declaration specifies a new annotation type, a special kind 
of interface type. To distinguish an annotation type declaration from a normal 
interface declaration, the keyword interface is preceded by an at-sign (@). 


AnnotationTypeDeclaration: 
{InterfaceModifier} @ interface Typeldentifier AnnotationTypeBody 


Note that the at-sign (@) and the keyword interface are distinct tokens. It is possible to 
separate them with whitespace, but this is discouraged as a matter of style. 


The rules for annotation modifiers on an annotation type declaration are specified 
in §9.7.4 and 89.7.5. 


The 7ypeldentifier in an annotation type declaration specifies the name of the 
annotation type. 


It is a compile-time error if an annotation type has the same simple name as any 
of its enclosing classes or interfaces. 


The direct superinterface of every annotation type is 


java.lang.annotation.Annotation. 


By virtue of the AnnotationTypeDeclaration syntax, an annotation type declaration cannot 
be generic, and no extends clause is permitted. 


A consequence of the fact that an annotation type cannot explicitly declare a superclass 
or superinterface is that a subclass or subinterface of an annotation type is never itself 
an annotation type. Similarly, java.lang.annotation.Annotation is not itself an 
annotation type. 


An annotation type inherits several members from 
java.lang.annotation.Annotation, including the implicitly declared methods 
corresponding to the instance methods of object, yet these methods do not define 
elements of the annotation type (§9.6.1). 


Because these methods do not define elements of the annotation type, it is illegal to use 
them in annotations of that type (§9.7). Without this rule, we could not ensure that elements 
were of the types representable in annotations, or that accessor methods for them would 
be available. 


Unless explicitly modified herein, all of the rules that apply to normal interface 
declarations apply to annotation type declarations. 
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For example, annotation types share the same namespace as normal class and interface 
types; and annotation type declarations are legal wherever interface declarations are legal, 
and have the same scope and accessibility. 


9.6.1 Annotation Type Elements 


The body of an annotation type declaration may contain method declarations, each 
of which defines an element of the annotation type. An annotation type has no 
elements other than those defined by the methods it explicitly declares. 


AnnotationTypeBody: 
{ {AnnotationTypeMemberDeclaration} } 


AnnotationTypeMemberDeclaration: 
AnnotationTypeElementDeclaration 
ConstantDeclaration 
ClassDeclaration 
InterfaceDeclaration 


’ 


AnnotationTypeElementDeclaration: 
{AnnotationTypeElementModifier} UnannType Identifier ( ) [Dims] 
[DefaultValue] ; 


AnnotationTypeElementModifier: 
(one of) 


Annotation public 


abstract 


By virtue of the AnnotationTypeElementDeclaration production, a method declaration in an 
annotation type declaration cannot have formal parameters, type parameters, or a throws 
clause. The following production from §4.3 is shown here for convenience: 


Dims: 
{Annotation} [| ] {{Annotation} [ ]} 


By virtue of the AnnotationTypeElementModifier production, a method declaration in an 
annotation type declaration cannot be default or static. Thus, an annotation type 
cannot declare the same variety of methods as a normal interface type. Note that it is still 
possible for an annotation type to inherit a default method from its implicit superinterface, 


java.lang.annotation.Annotation, though no such default method exists as of Java 
SE 12. 


By convention, the only AnnotationTypeElementModifiers that should be present on an 
annotation type element are annotations. 
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The return type of a method declared in an annotation type must be one of the 
following, or a compile-time error occurs: 


¢ A primitive type 

* String 

* Class or an invocation of Class (§4.5) 
e An enum type 

e An annotation type 


e An array type whose component type is one of the preceding types ($10.1). 
This rule precludes elements with nested array types, such as: 


@interface Verboten { 
String[][] value(); 
} 


The declaration of a method that returns an array is allowed to place the bracket 
pair that denotes the array type after the empty formal parameter list. This syntax is 
supported for compatibility with early versions of the Java programming language. 
It is very strongly recommended that this syntax is not used in new code. 


It is a compile-time error if any method declared in an annotation type has a 
signature that is override-equivalent to that of any public or protected method 
declared in class object or in the interface java.lang.annotation.Annotation. 


It is a compile-time error if an annotation type declaration T contains an element 
of type r, either directly or indirectly. 


For example, this is illegal: 
@interface SelfRef { SelfRef value(); } 
and so is this: 


@interface Ping { Pong value(); } 
@interface Pong { Ping value(); } 


An annotation type with no elements is called a marker annotation type. 
An annotation type with one element is called a single-element annotation type. 


By convention, the name of the sole element in a single-element annotation type 
iS value. Linguistic support for this convention is provided by single-element 
annotations (§9.7.3). 
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Example 9.6.1-1. Annotation Type Declaration 


The following annotation type declaration defines an annotation type with several elements: 


[** 
* Describes the "request-—for-enhancement" (RFE) 
* that led to the presence of the annotated API element. 
*/ 
@interface RequestForEnhancement { 
int TRO // Unique ID number associated with RFE 
String synopsis(); // Synopsis of RFE 
String engineer(); // Name of engineer who implemented RFE 
String date(); // Date RFE was implemented 


Example 9.6.1-2. Marker Annotation Type Declaration 


The following annotation type declaration defines a marker annotation type: 


[** 

* An annotation with this type indicates that the 
* specification of the annotated API element is 

* preliminary and subject to change. 

*/ 


@interface Preliminary {} 


Example 9.6.1-3. Single-Element Annotation Type Declarations 


The convention that a single-element annotation type defines an element called value is 
illustrated in the following annotation type declaration: 


[** 
* Associates a copyright notice with the annotated API element. 
af 
@interface Copyright { 
String value(); 


The following annotation type declaration defines a single-element annotation type whose 
sole element has an array type: 


[** 
* Associates a list of endorsers with the annotated class. 
*/ 
@interface Endorsers { 
String[] value(); 


The following annotation type declaration shows a Class-typed element whose value is 
constrained by a bounded wildcard: 
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interface Formatter {} 


// Designates a formatter to pretty-print the annotated class 
@interface PrettyPrinter { 
Class<? extends Formatter> value(); 


The following annotation type declaration contains an element whose type is also an 
annotation type: 


[** 
* Indicates the author of the annotated program element. 
ay 
@interface Author { 
Name value(); 
} 
[** 
* A person's name. This annotation type is not designed 
* to be used directly to annotate program elements, but to 
* define elements of other annotation types. 
*f 
@interface Name { 
String first(); 
String last(); 


The grammar for annotation type declarations permits other element declarations besides 
method declarations. For example, one might choose to declare a nested enum for use in 
conjunction with an annotation type: 


@interface Quality { 
enum Level { BAD, INDIFFERENT, GOOD } 
Level value(); 


9.6.2 Defaults for Annotation Type Elements 


An annotation type element may have a default value, specified by following the 
element's (empty) parameter list with the keyword default and an ElementValue 
($9.7.1). 


DefaultValue: 
default ElementValue 


It is a compile-time error if the type of the element is not commensurate (§9.7) with 
the default value specified. 


Default values are not compiled into annotations, but rather applied dynamically 
at the time annotations are read. Thus, changing a default value affects annotations 
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even in classes that were compiled before the change was made (presuming these 
annotations lack an explicit value for the defaulted element). 


Example 9.6.2-1. Annotation Type Declaration With Default Values 


Here is a refinement of the Request ForEnhancement annotation type from §9.6.1: 


@interface RequestForEnhancementDefault { 
// No default - must be specified in 
// each annotation 


int 


String 


String 
String 


id ( 


i 


synopsis (); 


engineer () 
date () 


// each annotation 


default "[unassigned]"; 


// No default - must be specified in 


default "[unimplemented]"; 


9.6.3 Repeatable Annotation Types 


An annotation type r is repeatable if its declaration is (meta-)annotated with an 
@Repeatable annotation (§9.6.4.8) whose value element indicates a containing 
annotation type of T. 


An annotation type Tc is a containing annotation type of T if all of the following 


are true: 


1. rcdeclares a value () method whose return type is T[]. 


2. Any methods declared by rc other than value () have a default value. 


3. rc is retained for at least as long as 7, where retention is expressed explicitly 
or implicitly with the @Retention annotation (§9.6.4.2). Specifically: 


e If 


java.lang.annotation.RetentionPolicy.SOURCE 


e If the retention of Tcis java.lang.annotation.Re 


then 


java. 


. lang. 


lang. 


the 


the 
anno 


anno 


the 


-anno 


1S 


-anno 


-anno 


ta 


ta 


ta 


ta 


ta 


retention 


retention 


tion.Re 


tion.Re 


tion.Re 


tion.Re 


tion.Re 


cen 


ten 


cen 


ten 


cen 


retention 
tionPolicy.RUNTIM 


java.lang.annotation. 


tionPolicy.CLASS 


of 


of Tr 


tionPolicy.SOURCE. 


of 


TC is 


, then the retention of T 


is java.lang.annotation.RetentionPolicy.SOURCE. 


tentionPolicy.CLASS, 


is either 
or 
TC is 


E, then the retention 


RetentionPolicy.SOURCE, 
tionPolicy.CLASS, 


tionPolicy.RUNTIME. 


or 


INTERFACES Annotation Types 9.6 


4. Tis applicable to at least the same kinds of program element as rc (§9.6.4.1). 
Specifically, if the kinds of program element where ris applicable are denoted 
by the set m;, and the kinds of program element where rc is applicable are 
denoted by the set mz, then each kind in mz must occur in m;, except that: 


e If the kind in mp is 
java.lang.annotation.ElementType.ANNOTATION_TYPE, then at least 
one of java.lang.annotation.ElementType.ANNOTATION_TYPE or 


= 


java.lang.annotation.ElementType.TYPE or 
java.lang.annotation.ElementType.TYPE_USE must occur iN mj. 


e If the kind in m is java.lang.annotation.ElementType.TYPE 
then at least one of java.lang.annotation.ElementType.TYPE OF 
java.lang.annotation.ElementType.TYPE_USE must occur iN mj. 


e If the kind in mp is 
java.lang.annotation.ElementType.TYPE_PARAMETER, then at least 
one of java.lang.annotation.ElementType.TYPE_PARAMETER or 
java.lang.annotation.ElementType.TYPE_USE must occur in mj. 


This clause implements the policy that an annotation type may be repeatable on only 
some of the kinds of program element where it is applicable. 


5. If the declaration of r has a (meta-)annotation that corresponds to 
java.lang.annotation.Documented, then the declaration of rc must have a 
(meta-)annotation that corresponds to java. 1lang.annotation.Documented. 


Note that it is permissible for Tc to be @Documented while T is not @Documented. 


6. If the declaration of r has a (meta-)annotation that corresponds to 
java.lang.annotation. Inherited, then the declaration of Tc must have a 
(meta)-annotation that corresponds to java.lang.annotation. Inherited. 


Note that it is permissible for Tc to be @Inherited while T is not @Inherited. 


It is a compile-time error if an annotation type T is (meta-)annotated with an 
@Repeatable annotation whose value element indicates a type which is not a 
containing annotation type of rT. 


Example 9.6.3-1. Ill-formed Containing Annotation Type 
Consider the following declarations: 


import java.lang.annotation.Repeatable; 


@Repeatable (FooContainer.class) 
@interface Foo {} 
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@interface FooContainer { Object[] value(); } 


Compiling the Foo declaration produces a compile-time error because Foo uses 
@Repeatable to attempt to specify FooContainer as its containing annotation type, but 
FooContainer is not in fact a containing annotation type of Foo. (The return type of 
FooContainer.value() is not Foo[].) 


The @Repeat able annotation cannot be repeated, so only one containing annotation 
type can be specified by a repeatable annotation type. 


Allowing more than one containing annotation type to be specified would cause an 
undesirable choice at compile time, when multiple annotations of the repeatable annotation 
type are logically replaced with a container annotation (§9.7.5). 


An annotation type can be the containing annotation type of at most one annotation 
type. 


This is implied by the requirement that if the declaration of an annotation type T specifies 
a containing annotation type of Tc, then the value() method of rc has a return type 
involving T, specifically T[1]. 


An annotation type cannot specify itself as its containing annotation type. 


This is implied by the requirement on the value () method of the containing annotation 
type. Specifically, if an annotation type A specified itself (via @Repeatable) as its 
containing annotation type, then the return type of A's value () method would have to be 
A[]; but this would cause a compile-time error since an annotation type cannot refer to itself 
in its elements (§9.6.1). More generally, two annotation types cannot specify each other to 
be their containing annotation types, because cyclic annotation type declarations are illegal. 


An annotation type Tc may be the containing annotation type of some annotation 
type T while also having its own containing annotation type rc '. That is, a 
containing annotation type may itself be a repeatable annotation type. 


Example 9.6.3-2. Restricting Where Annotations May Repeat 


An annotation whose type declaration indicates a target of 
java.lang.annotation.ElementType.TYPE can appear in at least as many 
locations as an annotation whose type declaration indicates a target of 
java.lang.annotation.ElementType.ANNOTATION_TYPE. For example, given the 
following declarations of repeatable and containing annotation types: 


import java.lang.annotation.Target; 
import java.lang.annotation.ElementType; 
import java.lang.annotation.Repeatable; 


@Target (ElementType. TYPE) 
@Repeatable (FooContainer.class) 
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@interface Foo {} 


@Target (Element Type .ANNOTATION_TYPE) 
@interface FooContainer { 
Foo[] value(); 


@Foo can appear on any type declaration while @FooContainer can appear on only 
annotation type declarations. Therefore, the following annotation type declaration is legal: 


@Foo @Foo 
@interface Anno {} 


while the following interface declaration is illegal: 


@Foo @Foo 
interface Intf {} 


More broadly, if Foo is a repeatable annotation type and FooContainer is its containing 
annotation type, then: 


¢ If Foo has no @Target meta-annotation and FooContainer has no @Target meta- 
annotation, then @Foo may be repeated on any program element which supports 
annotations. 


¢ If Foo has no @Target meta-annotation but FooContainer has an @Target 
meta-annotation, then @Foo may only be repeated on program elements where 
@FooContainer May appear. 


¢ If Foo has an @Target meta-annotation, then in the judgment of the designers of the 
Java programming language, FooContainer must be declared with knowledge of the 
Foo's applicability. Specifically, the kinds of program element where FooContainer 
may appear must logically be the same as, or a subset of, Foo's kinds. 


For example, if Foo is applicable to field and method declarations, then 
FooContainer may legitimately serve as Foo's containing annotation type if 
FooContainer is applicable to just field declarations (preventing @Foo from 
being repeated on method declarations). But if FooContainer is applicable only 
to formal parameter declarations, then FooContainer was a poor choice of 
containing annotation type by Foo because @FooContainer cannot be implicitly 
declared on some program elements where @Foo is repeated. 


Similarly, if Foo is applicable to field and method declarations, then 
FooContainer cannot legitimately serve as Foo's containing annotation type if 
FooContainer is applicable to field and parameter declarations. While it would 
be possible to take the intersection of the program elements and make Foo 
repeatable on field declarations only, the presence of additional program elements 
for FooContainer indicates that FooContainer was not designed as a containing 
annotation type for Foo. It would therefore be dangerous for Foo to rely on it. 
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Example 9.6.3-3. A Repeatable Containing Annotation Type 
The following declarations are legal: 


import java.lang.annotation.Repeatable; 


// Foo: Repeatable annotation type 
@Repeatable (FooContainer.class) 
@interface Foo { int value(); } 


// FooContainer: Containing annotation type of Foo 

// Also a repeatable annotation type itself 
@Repeatable (FooContainerContainer.class) 

@interface FooContainer { Foo[] value(); } 


// FooContainerContainer: Containing annotation type of FooContainer 
@interface FooContainerContainer { FooContainer[] value(); } 


Thus, an annotation whose type is a containing annotation type may itself be repeated: 


@FooContainer({@Foo(1)}) @FooContainer ({@Foo (2) }) 
class Test {} 


An annotation type which is both repeatable and containing is subject to the rules on 
mixing annotations of repeatable annotation type with annotations of containing annotation 
type (§9.7.5). For example, it is not possible to write multiple @Foo annotations alongside 
multiple @FooCont ainer annotations, nor is it possible to write multiple @FooContainer 
annotations alongside multiple @FooContainerContainer annotations. However, if the 
FooContainerContainer type was itself repeatable, then it would be possible to write 
multiple @Foo annotations alongside multiple @FooContainerContainer annotations. 


9.6.4 Predefined Annotation Types 


Several annotation types are predefined in the libraries of the Java SE Platform. 
Some of these predefined annotation types have special semantics. These semantics 
are specified in this section. This section does not provide a complete specification 
for the predefined annotations contained here in; that is the role of the appropriate 
API specifications. Only those semantics that require special behavior on the part 
of a Java compiler or Java Virtual Machine implementation are specified here. 


9.6.4.1 @Target 


An annotation of type java.lang.annotation.Target is used on _ the 
declaration of an annotation type Tr to specify the contexts in which T is 
applicable. java.lang.annotation.Target has a single element, value, of type 
java.lang.annotation.ElementType[], to specify contexts. 
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Annotation types may be applicable in declaration contexts, where annotations 
apply to declarations, or in type contexts, where annotations apply to types used in 
declarations and expressions. 


There are nine declaration contexts, each corresponding to an enum constant of 


java.lang.annotation.ElementType: 


1. Module declarations (§7.7) 


Corresponds to java.lang.annotation.ElementType.MODULE 
2. Package declarations (§7.4.1) 


Corresponds to java.lang.annotation.ElementType.PACKAGE 


3. Type declarations: class, interface, enum, and annotation type declarations 
(§8.1.1, §9.1.1, $8.5, $9.5, §8.9, §9.6) 


Corresponds to java.lang.annotation.ElementType.TYPE 


Additionally, annotation type declarations correspond to 
java.lang.annotation.ElementType.ANNOTATION_TYPE 


4. Method declarations (including elements of annotation types) (§8.4.3, $9.4, 
§9.6.1) 


Corresponds to java.lang.annotation.ElementType.METHOD 


5. Constructor declarations (§8.8.3) 
Corresponds to java.lang.annotation.ElementType.CONSTRUCTOR 


6. Type parameter declarations of generic classes, interfaces, methods, and 
constructors (§8.1.2, §9.1.2, §8.4.4, §8.8.4) 


Corresponds to java.lang.annotation.ElementType.TYPE_PARAMETER 


7. Field declarations (including enum constants) (§8.3.1, §9.3, §8.9.1) 


Corresponds to java.lang.annotation.ElementType.FIELD 


8. Formal and exception parameter declarations (§8.4.1, §9.4, §14.20) 


Corresponds to java.lang.annotation.ElementType.PARAMETER 


9. Local variable declarations (including loop variables of for statements 
and resource variables of try-with-resources statements) (§14.4, §14.14.1, 
§14.14.2, §14.20.3) 


Corresponds to java.lang.annotation.ElementType.LOCAL_VARIABLE 
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There are 16 type contexts (§4.11), all represented by the enum constant TYPE_USE 


of java.lang.annotation.ElementType. 


It is a compile-time error if the same enum constant appears more than once in the 
value element of an annotation of type java.lang.annotation.Target. 


If an annotation of type java.lang.annotation.Target is not present on the 
declaration of an annotation type r, then Tis applicable in all declaration contexts 
except type parameter declarations, and in no type contexts. 


These contexts are the syntactic locations where annotations were allowed in Java SE 7. 


9.6.4.2 @Retention 


Annotations may be present only in source code, or they may be present in the 
binary form of a class or interface. An annotation that is present in the binary form 
may or may not be available at run time via the reflection libraries of the Java 
SE Platform. The annotation type java.lang.annotation.Retention is used to 
choose among these possibilities. 


If an annotation a corresponds to a type r, and r has a (meta-)annotation m that 
corresponds to java.lang.annotation.Retention, then: 


e If m has an element whose value is 
java.lang.annotation.RetentionPolicy. SOURCE, then a Java compiler must 
ensure that a is not present in the binary representation of the class or interface 
in which a appears. 


e If m has an element whose value is 
java.lang.annotation.RetentionPolicy.CLASS or 
java.lang.annotation.RetentionPolicy.RUNTIME, then a Java compiler 
must ensure that a is represented in the binary representation of the class or 
interface in which a appears, unless a annotates a local variable declaration or a 
annotates a formal parameter declaration of a lambda expression. 


An annotation on the declaration of a local variable, or on the declaration of 
a formal parameter of a lambda expression, is never retained in the binary 
representation. In contrast, an annotation on the type of a local variable, or on 
the type of a formal parameter of a lambda expression, is retained in the binary 
representation if the annotation type specifies a suitable retention policy. 


Note that it is not illegal for an annotation type to be meta-annotated 
with @Target (java.lang.annotation.ElementType.LOCAL_VARIABLE) and 
@Retention(java.lang.annotation.RetentionPolicy.CLASS) or 
@Retention(java.lang.annotation.RetentionPolicy.RUNTIME). 
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If m has an element whose value is 
java.lang.annotation.RetentionPolicy.RUNTIME, the reflection libraries of 
the Java SE Platform must make a available at run time. 


If tr does not have a_ (meta-)annotation m that corresponds _ to 
java.lang.annotation.Retention, then a Java compiler must treat rT as if 
it does have such a meta-annotation m with an element whose value is 


java.lang.annotation.RetentionPolicy.CLASS. 


9.6.4.3 @Inherited 


The annotation type java.lang.annotation.Inherited is used to indicate that 
annotations on a class c corresponding to a given annotation type are inherited by 
subclasses of c. 


9.6.4.4 @override 


Programmers occasionally overload a method declaration when they mean to 
override it, leading to subtle problems. The annotation type Override supports 
early detection of such problems. 


The classic example concerns the equals method. Programmers write the following in 
class Foo: 


public boolean equals(Foo that) { ... } 
when they mean to write: 
public boolean equals(Object that) { ... } 


This is perfectly legal, but class Foo inherits the equals implementation from Object, 
which can cause some subtle bugs. 


If a method declaration in type Tis annotated with @override, but the method does 
not override from ra method declared in a supertype of r (§8.4.8.1, §9.4.1.1), or 
is not override-equivalent to a public method of object (§4.3.2, §8.4.2), then a 
compile-time error occurs. 


This behavior differs from Java SE 5.0, where @Override only caused a compile-time 
error if applied to a method that implemented a method from a superinterface that was not 
also present in a superclass. 


The clause about overriding a public method is motivated by use of @Override in an 
interface. Consider the following type declarations: 
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class Foo { @Override public int hashCode() {..} } 
interface Bar { @Override int hashCode(); } 


The use of @Override in the class declaration is legal by the first clause, because 
Foo.hashCode overrides from Foo the method Object .hashCode. 


For the interface declaration, consider that while an interface does not have Object as 
a supertype, an interface does have public abstract members that correspond to the 
public members of Object (§9.2). If an interface chooses to declare them explicitly (that 
is, to declare members that are override-equivalent to public methods of Object), then 
the interface is deemed to override them, and use of @Override is allowed. 


However, consider an interface that attempts to use @Override on a clone method: 
(finalize could also be used in this example) 


interface Quux { @Override Object clone(); } 


Because Object.clone is not public, there is no member called clone implicitly 
declared in Quux. Therefore, the explicit declaration of clone in Quux is not deemed 
to "implement" any other method, and it is erroneous to use @Override. (The fact that 
Quux.clone is public is not relevant.) 


In contrast, a class declaration that declares clone is simply overriding Object .clone, 
so is able to use @Override: 


class Beep { @Override protected Object clone() {..} } 


9.6.4.5 @SuppressWarnings 


Java compilers are increasingly capable of issuing helpful "lint-like" warnings. 
To encourage the use of such warnings, there should be some way to disable a 
warning in a part of the program when the programmer knows that the warning is 
inappropriate. 


The annotation type SuppressWarnings supports programmer control over 
warnings otherwise issued by a Java compiler. It defines a single element that is 
an array of String. 


If a declaration is annotated with @SuppressWarnings (value = {S1, ..., Sx}), 
then a Java compiler must suppress (that is, not report) any warning specified by 
one of s,... S, if that warning would have been generated as a result of the annotated 
declaration or any of its parts. 


The three kinds of warnings defined by the Java programming language are 
specified using the following strings: 


¢ Unchecked warnings (§4.8, §5.1.6, §5.1.9, 88.4.1, §8.4.8.3, §15.12.4.2, 
§15.13.2, §15.27.3) are specified by the string "unchecked". 
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¢ Deprecation warnings (§9.6.4.6) are specified by the string "deprecation". 


¢ Removal warnings (§9.6.4.6) are specified by the string "removal". 


For other kinds of warnings, compiler vendors should document the strings they support 
for @SuppressWarnings. Vendors are encouraged to cooperate to ensure that the same 
names work across multiple compilers. 


9.6.4.6 @Deprecated 


Programmers are sometimes discouraged from using certain program elements 
(modules, types, fields, methods, and constructors) because they are dangerous 
or because a better alternative exists. The annotation type Deprecated allows a 
compiler to warn about uses of these program elements. 


A deprecated program element is a module, type, field, method, or constructor 
whose declaration is annotated with eDeprecated. The manner in which a program 
element is deprecated depends on the value of the forRemoval element of the 
annotation: 


¢ If forRemoval=false (the default), then the program element is ordinarily 
deprecated. 


An ordinarily deprecated program element is not intended to be removed in a 
future release, but programmers should nevertheless migrate away from using it. 


¢ If forRemoval=true, then the program element is terminally deprecated. 


A terminally deprecated program element is intended to be removed in a 
future release. Programmers should stop using it or risk source and binary 
incompatibilities ($13.2) when upgrading to a newer release. 


A Java compiler must produce a deprecation warning when an ordinarily 
deprecated program element is used (overridden, invoked, or referenced by name) 
in the declaration of a program element (whether explicitly or implicitly declared), 
unless: 


¢ The use is within a declaration that is itself deprecated, either ordinarily or 
terminally; or 


e The use is within a declaration that is annotated to suppress deprecation 
warnings; or 


¢ The use and declaration are both within the same outermost class; or 


¢ The use is within an import declaration that imports the ordinarily deprecated 
type or member. 
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e The use is within an exports or opens directive (§7.7.2). 


A Java compiler must produce a removal warning when a terminally deprecated 
program element is used (overridden, invoked, or referenced by name) in the 
declaration of a program element (whether explicitly or implicitly declared), 
unless: 


¢ The use is within a declaration that is annotated to suppress removal warnings; or 
¢ The use and declaration are both within the same outermost class; or 


¢ The use is within an import declaration that imports the terminally deprecated 
type or member. 


e The use is within an exports Or opens directive. 


Terminal deprecation is sufficiently urgent that the use of a terminally deprecated element 
will cause a removal warning even if the using element is itself deprecated, since there is 
no guarantee that both elements will be removed at the same time. To dismiss the warning 
but continue using the element, the programmer must manually acknowledge the risk via 
an @SuppressWarnings annotation. 


No deprecation warning or removal warning is produced when: 


¢ a local variable or formal parameter is used (referenced by name), even if 
the declaration of the local variable or formal parameter is annotated with 
@Deprecated. 


¢ the name of a package is used (referenced by a qualified type name, or an import 
declaration, or an exports Or opens directive), even if the declaration of the 
package is annotated with @Deprecated. 


¢ the name of a module is used by a qualified exports or opens directive, even if 
the declaration of the friend module is annotated with @Deprecated. 


A module declaration that exports or opens a package is usually controlled by the same 
programmer or team that controls the package's declaration. As such, there is little benefit in 
warning that the package declaration is annotated with @Deprecated when the package is 
exported or opened by the module declaration. In contrast, a module declaration that exports 
or opens a package to a friend module is usually not controlled by the same programmer 
or team that controls the friend module. Simply exporting or opening the package does not 
make the module declaration rely on the friend module, so there is little value in warning if 
the friend module is deprecated; the programmer of the module declaration would almost 
always wish to suppress such a warning. 


The only implicit declaration that can cause a deprecation warning or removal warning 
is a container annotation (§9.7.5). Namely, if T is a repeatable annotation type and Tc 
is its containing annotation type, and rc is deprecated, then repeating the @T annotation 
will cause a warning. The warning is due to the implicit @Tc container annotation. It is 
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strongly discouraged to deprecate a containing annotation type without deprecating the 
corresponding repeatable annotation type. 


9.6.4.7 @SafeVarargs 


A variable arity parameter with a non-reifiable element type (§4.7) can cause heap 
pollution (§4.12.2) and give rise to compile-time unchecked warnings (§5.1.9). 
Such warnings are uninformative if the body of the variable arity method is well- 
behaved with respect to the variable arity parameter. 


The annotation type SafeVarargs, when used to annotate a method or constructor 
declaration, makes a programmer assertion that prevents a Java compiler from 
reporting unchecked warnings for the declaration or invocation of a variable arity 
method or constructor where the compiler would otherwise do so due to the variable 
arity parameter having a non-reifiable element type. 


The annotation @SafeVarargs has non-local effects because it suppresses unchecked 
warnings at method invocation expressions, in addition to an unchecked warning pertaining 
to the declaration of the variable arity method itself (§8.4.1). In contrast, the annotation 
@SuppressWarnings ("unchecked") has local effects because it only suppresses 
unchecked warnings pertaining to the declaration of a method. 


The canonical target for @SafeVarargs is a method like 
java.util.Collections.addAl11, whose declaration starts with: 


public static <T> boolean 
addAll(Collection<? super T> c, T... elements) 


The variable arity parameter has declared type T[], which is non-reifiable. However, 
the method fundamentally just reads from the input array and adds the elements 
to a collection, both of which are safe operations with respect to the array. 
Therefore, any compile-time unchecked warnings at method invocation expressions for 
java.util.Collections.addAl1 are arguably spurious and uninformative. Applying 
@SafeVarargs to the method declaration prevents generation of these unchecked warnings 
at the method invocation expressions. 


It is a compile-time error if a fixed arity method or constructor declaration is 
annotated with the annotation @SafeVarargs. 


It is a compile-time error if a variable arity method declaration that is neither 
static nor final nor private is annotated with the annotation @Safevarargs. 


Since @SafeVarargs is only applicable to static methods, final and/or private 
instance methods, and constructors, the annotation is not usable where method overriding 
occurs. Annotation inheritance only works for annotations on classes (not on methods, 
interfaces, or constructors), so an @SafeVarargs-style annotation cannot be passed 
through instance methods in classes or through interfaces. 
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9.6.4.8 @Repeatable 


The annotation type java.lang.annotation.Repeatable is used on the 
declaration of a repeatable annotation type to indicate its containing annotation 


type (§9.6.3). 


Note that an @Repeatable meta-annotation on the declaration of T, indicating TC, is 
not sufficient to make Tc the containing annotation type of rT. There are numerous well- 
formedness rules for Tc to be considered the containing annotation type of T. 


9.6.4.9 @FunctionaliInterface 


The annotation type FunctionaliInterface is used to indicate that an interface 
is meant to be a functional interface (§9.8). It facilitates early detection of 
inappropriate method declarations appearing in or inherited by an interface that is 
meant to be functional. 


It is a compile-time error if an interface declaration is annotated with 
@Functionalinterface but is not, in fact, a functional interface. 


Because some interfaces are functional incidentally, it is not necessary or 
desirable that all declarations of functional interfaces be annotated with 


@FunctionalliInterface. 


9.7 Annotations 


An annotation is a marker which associates information with a program construct, 
but has no effect at run time. An annotation denotes a specific invocation of an 
annotation type ($9.6) and usually provides values for the elements of that type. 


There are three kinds of annotations. The first kind is the most general, while the 
other kinds are merely shorthands for the first kind. 


Annotation: 
NormalAnnotation 
MarkerAnnotation 
SingleElementAnnotation 


Normal annotations are described in §9.7.1, marker annotations in §9.7.2, and 
single element annotations in §9.7.3. Annotations may appear at various syntactic 
locations in a program, as described in §9.7.4. The number of annotations of the 
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same type that may appear at a location is determined by their type, as described 
in §9.7.5. 


9.7.1 Normal Annotations 


A normal annotation specifies the name of an annotation type and optionally a list 
of comma-separated element-value pairs. Each pair contains an element value that 
is associated with an element of the annotation type (§9.6.1). 


NormalAnnotation: 
@ TypeName ( [ElementValuePairList] ) 


ElementValuePairList: 
ElementValuePair {, ElementValuePair} 


ElementValuePair: 
Identifier = ElementValue 


ElementValue: 
ConditionalExpression 
ElementValueArraylnitializer 
Annotation 


ElementValueArrayInitializer: 
{ [ElementValueList] [,] } 


ElementValue List: 
ElementValue {, ElementValue} 


Note that the at-sign (@) is a token unto itself ($3.11). It is possible to put whitespace 
between it and the TypeName, but this is discouraged as a matter of style. 


The TypeName specifies the annotation type corresponding to the annotation. The 
annotation is said to be "of" that type. 


The TypeName must name an accessible annotation type (§6.6), or a compile-time 
error occurs. 


The /dentifier in an element-value pair must be the simple name of one of the 
elements (that is, methods) of the annotation type, or a compile-time error occurs. 


The return type of this method defines the element type of the element-value pair. 
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If the element type is an array type, then it is not required to use curly 
braces to specify the element value of the element-value pair. If the element 
value is not an ElementValueArraylnitializer, then an array value whose sole 
element is the element value is associated with the element. If the element 
value is an ElementValueArraylInitializer, then the array value represented by the 
ElementValueArraylnitializer is associated with the element. 


It is a compile-time error if the element type is not commensurate with the element 
value. An element type T is commensurate with an element value vif and only if 
one of the following is true: 


* Tis an array type £[], and either: 


— If vis a ConditionalExpression or an Annotation, then vis commensurate with 
E; or 


— If vis an ElementValueArrayInitializer, then each element value that v 
contains is commensurate with £. 


An ElementValueArraylnitializer is similar to a normal array initializer ($10.6), 
except that an ElementValueArrayInitializer may syntactically contain annotations 
as well as expressions and nested initializers. However, nested initializers are 
not semantically legal in an ElementValueArraylnitializer because they are never 
commensurate with array-typed elements in annotation type declarations (nested array 
types not permitted). 


¢ ris not an array type, and the type of v is assignment compatible (§5.2) with 
T, and: 


— If ris a primitive type or string, then vis a constant expression ($15.28). 
— If ris Class or an invocation of class (§4.5), then visa class literal (§15.8.2). 
— If ris an enum type (§8.9), then vis an enum constant (§8.9.1). 


— vis not null. 


Note that if T is not an array type or an annotation type, the element value must be a 
ConditionalExpression (§15.25). The use of ConditionalExpression rather than a more 
general production like Expression is a syntactic trick to prevent assignment expressions 
as element values. Since an assignment expression is not a constant expression, it cannot 
be a commensurate element value for a primitive or St ring-typed element. 


Formally, it is invalid to speak of an ElementValue as FP-strict (§15.4) because it might be 
an annotation or a class literal. Still, we can speak informally of ElementValue as FP-strict 
when it is either a constant expression or an array of constant expressions or an annotation 
whose element values are (recursively) found to be constant expressions; after all, every 
constant expression is FP-strict. 
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A normal annotation must contain an element-value pair for every element of the 
corresponding annotation type, except for those elements with default values, or a 
compile-time error occurs. 


A normal annotation may, but is not required to, contain element-value pairs for 
elements with default values. 


It is customary, though not required, that element-value pairs in an annotation are presented 
in the same order as the corresponding elements in the annotation type declaration. 


An annotation on an annotation type declaration is known as a meta-annotation. 


An annotation of type T may appear as a meta-annotation on the declaration of type 
T itself. More generally, circularities in the transitive closure of the "annotates" 
relation are permitted. 


For example, it is legal to annotate the declaration of an annotation type s with a meta- 
annotation of type T, and to annotate T's own declaration with a meta-annotation of type s. 
The pre-defined annotation types contain several such circularities. 


Example 9.7.1-1. Normal Annotations 


Here is an example of a normal annotation using the annotation type from §9.6.1: 


@RequestForEnhancement ( 


id = 2868724, 
synopsis = "Provide time-travel functionality", 
engineer = "Mr. Peabody", 
date = "4/1/2004" 
) 
public static void travelThroughTime (Date destination) { ... } 


Here is an example of a normal annotation that takes advantage of default values, using the 
annotation type from §9.6.2: 


@RequestForEnhancement ( 
id = 4561414, 
synopsis = "Balance the federal budget" 
) 
public static void balanceFederalBudget() { 
throw new UnsupportedOperationException ("Not implemented") ; 


9.7.2 Marker Annotations 


A marker annotation is a shorthand designed for use with marker annotation types 
(§9.6.1). 


9.7 


331 


9.7 Annotations INTERFACES 


MarkerAnnotation: 
@ TypeName 


It is shorthand for the normal annotation: 


@ TypeName () 


It is legal to use marker annotations for annotation types with elements, so long as 
all the elements have default values (§9.6.2). 


Example 9.7.2-1. Marker Annotations 


Here is an example using the Preliminary marker annotation type from §9.6.1: 


@Preliminary public class TimeTravel { ... } 


9.7.3 Single-Element Annotations 


A single-element annotation, is a shorthand designed for use with single-element 
annotation types (§9.6.1). 


SingleElementAnnotation: 
@ TypeName ( ElementValue ) 


It is shorthand for the normal annotation: 


@TypeName (value = ElementValue) 


It is legal to use single-element annotations for annotation types with multiple 
elements, so long as one element is named value and all other elements have 
default values (§9.6.2). 


Example 9.7.3-1. Single-Element Annotations 
The following annotations all use the single-element annotation types from §9.6.1. 
Here is an example of a single-element annotation: 


@Copyright ("2002 Yoyodyne Propulsion Systems, Inc.") 
public class OscillationOverthruster { ... } 


Here is an example of an array-valued single-element annotation: 


@Endorsers({"Children", "Unscrupulous dentists"}) 
public class Lollipop { ... } 


332 


INTERFACES Annotations 


Here is an example of a single-element array-valued single-element annotation: (note that 
the curly braces are omitted) 


@Endorsers ("Epicurus") 
public class Pleasure { ... } 


Here is an example of a single-element annotation with a Class-typed element whose value 
is constrained by a bounded wildcard. 


class GorgeousFormatter implements Formatter { ... } 


@PrettyPrinter (GorgeousFormatter.class) 
public class Petunia { ... } 


// T1llegal; String is not a subtype of Formatter 
@PrettyPrinter (String.class) 
public class Begonia { ... } 


Here is an example with of a single-element annotation that contains a normal annotation: 


@Author (@Name (first = "Joe", last = "Hacker") ) 
public class BitTwiddle { ... } 


Here is an example of a single-element annotation that uses an enum type defined inside 
the annotation type: 


@Quality (Quality.Level.GOOD) 
public class Karma { ... } 


9.7.4 Where Annotations May Appear 


A declaration annotation is an annotation that applies to a declaration, and whose 
own type is applicable in the declaration context (§9.6.4.1) represented by that 
declaration; or an annotation that applies to a class, interface, enum, annotation 
type, or type parameter declaration, and whose own type is applicable in type 
contexts (§4.11). 


A type annotation is an annotation that applies to a type (or any part of a type), and 
whose own type is applicable in type contexts. 


For example, given the field declaration: 
@Foo int f; 


@Foo is a declaration annotation on ¢£ if Foo is _ meta-annotated by 
@Target (Element Type.FIELD), and a type annotation on int if Foo is meta-annotated 
by @Target (ElementType.TYPE_USE). It is possible for @Foo to be both a declaration 
annotation and a type annotation simultaneously. 
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Type annotations can apply to an array type or any component type thereof (§10.1). 
For example, assuming that A, B, and C are annotation types meta-annotated with 
@Target (Element Type. TYPE_USE), then given the field declaration: 


@C int @A [] @B [] f; 


@A applies to the array type int [][], @B applies to its component type int[], and @c 
applies to the element type int. For more examples, see §10.2. 


An important property of this syntax is that, in two declarations that differ only in the 
number of array levels, the annotations to the left of the type refer to the same type. For 
example, @c applies to the type int in all of the following declarations: 


@c int f; 
@c int[] f; 
@c int[][] f; 


It is customary, though not required, to write declaration annotations before all other 
modifiers, and type annotations immediately before the type to which they apply. 


It is possible for an annotation to appear at a syntactic location in a program where 
it could plausibly apply to a declaration, or a type, or both. This can happen in any 
of the five declaration contexts where modifiers immediately precede the type of 
the declared entity: 


Method declarations (including elements of annotation types) 
Constructor declarations 

Field declarations (including enum constants) 

Formal and exception parameter declarations 


Local variable declarations (including loop variables of for statements and 
resource variables of try-with-resources statements) 


The grammar of the Java programming language unambiguously treats annotations 
at these locations as modifiers for a declaration (§8.3), but that is purely a syntactic 
matter. Whether an annotation applies to the declaration or to the type of the 
declared entity - and thus, whether the annotation is a declaration annotation or a 
type annotation - depends on the applicability of the annotation's type: 


If the annotation's type is applicable in the declaration context corresponding to 
the declaration, and not in type contexts, then the annotation is deemed to apply 
only to the declaration. 


If the annotation's type is applicable in type contexts, and not in the declaration 
context corresponding to the declaration, then the annotation is deemed to apply 
only to the type which is closest to the annotation. 
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If the annotation's type is applicable in the declaration context corresponding to 
the declaration and in type contexts, then the annotation is deemed to apply to 
both the declaration and the type which is closest to the annotation. 


In the second and third cases above, the type which is closest to the annotation is 
determined as follows: 


If the annotation appears before a void method declaration or a local variable 
declaration that uses var (§14.4, §14.14.2, §14.20.3), then there is no closest 
type. If the annotation's type is deemed to apply only to the type which is closest 
to the annotation, a compile-time error occurs. 


If the annotation appears before a constructor declaration, then the closest type is 
the type of the newly constructed object. The type of the newly constructed object 
is the fully qualified name of the type immediately enclosing the constructor 
declaration. Within that fully qualified name, the annotation applies to the simple 
type name indicated by the constructor declaration. 


In all other cases, the closest type is the type written in source code for the 
declared entity; if that type is an array type, then the element type is deemed to 
be closest to the annotation. 


For example, in the field declaration @Foo public static String f;, the type which 
is closest to @Foo is String. (If the type of the field declaration had been written as 
java.lang.String, then java.lang.String would be the type closest to @Foo, and 
later rules would prohibit a type annotation from applying to the package name java.) 
In the generic method declaration @Foo <T> int[] m() {...}, the type written for 
the declared entity is int [], so @Foo applies to the element type int. 


Local variable declarations which do not use var are similar to formal parameter 
declarations of lambda expressions, in that both allow declaration annotations and type 
annotations in source code, but only the type annotations can be stored in the class file. 


It is a compile-time error if an annotation of type T is syntactically a modifier for: 


a module declaration, but Tis not applicable to module declarations. 
a package declaration, but Tis not applicable to package declarations. 


aclass, interface, or enum declaration, but Tis not applicable to type declarations 
or type contexts; or an annotation type declaration, but 7 is not applicable to 
annotation type declarations or type declarations or type contexts. 


a method declaration (including an element of an annotation type), but Tis not 
applicable to method declarations or type contexts. 


a constructor declaration, but ris not applicable to constructor declarations or 
type contexts. 
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* atype parameter declaration of a generic class, interface, method, or constructor, 
but Tis not applicable to type parameter declarations or type contexts. 


¢ a field declaration (including an enum constant), but Tis not applicable to field 
declarations or type contexts. 


¢ a formal or exception parameter declaration, but 7 is not applicable to either 
formal and exception parameter declarations or type contexts. 


* areceiver parameter, but Tis not applicable to type contexts. 


¢ a local variable declaration (including a loop variable of a for statement or a 
resource variable of a try-with-resources statement), but 7 is not applicable to 
local variable declarations or type contexts. 


Five of these nine clauses mention "... or type contexts" because they characterize the five 
syntactic locations where an annotation could plausibly apply either to a declaration or to 
the type of a declared entity. Furthermore, two of the nine clauses - for class, interface, 
enum, and annotation type declarations, and for type parameter declarations - mention "... 
or type contexts" because it may be convenient to apply an annotation whose type is meta- 
annotated with @Target (ElementType.TYPE_USE) (thus, applicable in type contexts) 
to a type declaration. 


A type annotation is admissible if both of the following are true: 


¢ The simple name to which the annotation is closest is classified as a TypeName, 
not a PackageName. 


wom 


¢ If the simple name to which the annotation is closest is followed by "." and 
another TypeName - that is, the annotation appears as @Foo T.u - then u denotes 
an inner class of T. 


The intuition behind the second clause is that if outer.this is legal in a nested class 
enclosed by Outer, then Outer may be annotated because it represents the type of some 
object at run time. On the other hand, if outer. this is not legal - because the class where it 
appears has no enclosing instance of Outer at run time - then Outer may not be annotated 
because it is logically just a name, akin to components of a package name in a fully qualified 
type name. 


For example, in the following program, it is not possible to write A. this in the body of B, 
as B has no lexically enclosing instances (8.5.1). Therefore, it is not possible to apply @Foo 
to Ain the type A.B, because A is logically just a name, not a type. 


@Target (ElementType.TYPE_USE) 
@interface Foo {} 


class Test { 
class A { 
static class B {} 


} 
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@Foo A.B x; // Illegal 
} 


On the other hand, in the following program, it is possible to write C. this in the body of 
D. Therefore, it is possible to apply @Foo to Cc in the type C.D, because Cc represents the 
type of some object at run time. 


@Target (ElementType.TYPE_USE) 
@interface Foo {} 


class Test { 
static class C. 4 
class D {} 
} 


@Foo C.D x; // Legal 
} 


Finally, note that the second clause looks only one level deeper in a qualified type. This is 
because a static class may only be nested in a top level class or another static nested 
class. It is not possible to write a nest like: 


@Target (ElementType.TYPE_USE) 
@interface Foo {} 


class Test { 
class E { 
class F { 
static class G {} 
} 
} 


@Foo E.F.G x; 
} 


Assume for a moment that the nest was legal. In the type of field x, = and F would logically 
be names qualifying G, as E.F.this would be illegal in the body of G. Then, @Foo should 
not be legal next to E. Technically, however, @Foo would be admissible next to E because 
the next deepest term F denotes an inner class; but this is moot as the class nest is illegal 
in the first place. 


It is a compile-time error if an annotation of type T applies to the outermost level of 
a type in a type context, and ris not applicable in type contexts or the declaration 
context (if any) which occupies the same syntactic location. 


It is a compile-time error if an annotation of type r applies to a part of a type (that is, 
not the outermost level) in a type context, and ris not applicable in type contexts. 
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It is a compile-time error if an annotation of type r applies to a type (or any part of 
a type) in a type context, and rT is applicable in type contexts, and the annotation 
is not admissible. 


For example, assume an annotation type TA which is meta-annotated with just 
@Target (ElementType.TYPE_USE). The terms @TA java.lang.Object and 
java.@TA lang.Object are illegal because the simple name to which @TA is closest is 
classified as a package name. On the other hand, java.lang.@TA Object is legal. 


Note that the illegal terms are illegal "everywhere". The ban on annotating package names 
applies broadly: to locations which are solely type contexts, such as class ... extends 
@TA java.lang.Object {...}, and to locations which are both declaration and type 
contexts, such as @TA java.lang.Object £f;. (There are no locations which are solely 
declaration contexts where a package name could be annotated, as class, package, and type 
parameter declarations use only simple names.) 


If TA is additionally meta-annotated with @Target (ElementType.FIELD), then the term 
@TA java.lang.Object is legal in locations which are both declaration and type contexts, 
such as a field declaration @TA java.lang.Object £;. Here, @TA is deemed to apply 
to the declaration of £ (and not to the type java.lang.Object) because TA is applicable 
in the field declaration context. 


9.7.5 Multiple Annotations of the Same Type 


It is a compile-time error if multiple annotations of the same type T appear in a 
declaration context or type context, unless ris repeatable (§9.6.3) and both rand 
the containing annotation type of rare applicable in the declaration context or type 
context (§9.6.4.1). 


It is customary, though not required, for multiple annotations of the same type to appear 
contiguously. 


If a declaration context or type context has multiple annotations of a repeatable 
annotation type 1, then it is as if the context has no explicitly declared annotations 
of type rand one implicitly declared annotation of the containing annotation type 
of T. 


The implicitly declared annotation is called the container annotation, and the 
multiple annotations of type r which appeared in the context are called the base 
annotations. The elements of the (array-typed) value element of the container 
annotation are all the base annotations in the left-to-right order in which they 
appeared in the context. 


It is a compile-time error if, in a declaration context or type context, there are 
multiple annotations of a repeatable annotation type 7 and any annotations of the 
containing annotation type of T. 


INTERFACES Functional Interfaces 


In other words, it is not possible to repeat annotations where an annotation of the same type 
as their container also appears. This prohibits obtuse code like: 


@Foo(0) @Foo(1) @FooContainer ({@Foo (2) }) 
class A {} 


If this code was legal, then multiple levels of containment would be needed: first the 
annotations of type Foo would be contained by an implicitly declared container annotation 
of type FooContainer, then that annotation and the explicitly declared annotation of 
type FooContainer would be contained in yet another implicitly declared annotation. 
This complexity is undesirable in the judgment of the designers of the Java programming 
language. Another approach, treating the annotations of type Foo as if they had occurred 
alongside @Foo (2) in the explicit @FooContainer annotation, is undesirable because it 
could change how reflective programs interpret the @FooContainer annotation. 


It is a compile-time error if, in a declaration context or type context, there is 
one annotation of a repeatable annotation type rT and multiple annotations of the 
containing annotation type of rT. 


This rule is designed to allow the following code: 


@Foo(1) @FooContainer ({@Foo (2) }) 
class A {} 


With only one annotation of the repeatable annotation type Foo, no container annotation 
is implicitly declared, even if FooContainer is the containing annotation type of Foo. 
However, repeating the annotation of type FooContainer, as in: 


@Foo(1) @FooContainer({@Foo(2)}) @FooContainer ({@Foo (3) }) 
class A {} 


is prohibited, even if FooContainer is repeatable with a containing annotation type of its 
own. It is obtuse to repeat annotations which are themselves containers when an annotation 
of the underlying repeatable type is present. 


9.8 Functional Interfaces 


A functional interface is an interface that has just one abstract method (aside 
from the methods of object), and thus represents a single function contract. This 
"single" method may take the form of multiple abstract methods with override- 
equivalent signatures inherited from superinterfaces; in this case, the inherited 
methods logically represent a single method. 


For an interface 1, let wbe the set of abstract methods that are members of r that 
do not have the same signature as any public instance method of the class object 
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(§4.3.2). Then, zis a functional interface if there exists a method min m for which 
both of the following are true: 


¢ The signature of mis a subsignature (§8.4.2) of every method's signature in m. 
* mis return-type-substitutable (§8.4.5) for every method in m. 


In addition to the usual process of creating an interface instance by declaring and 
instantiating a class ($15.9), instances of functional interfaces can be created with 
method reference expressions and lambda expressions ($15.13, §15.27). 


The definition of functional interface excludes methods in an interface that are also 
public methods in Object. This is to allow functional treatment of an interface like 
java.util.Comparator<T> that declares multiple abstract methods of which only 
one is really "new" - int compare (T,T). The other - boolean equals (Object) -is an 
explicit declaration of an abstract method that would otherwise be implicitly declared 
in the interface ($9.2) and automatically implemented by every class that implements the 
interface. 


Note that if non-public methods of Object, such as clone (), are explicitly declared 
in an interface as public, they are not automatically implemented by every class that 
implements the interface. The implementation inherited from Object is protected 
while the interface method is public, so the only way to implement the interface would 
be for a class to override the non-public Object method with a public method. 


Example 9.8-1. Functional Interfaces 


A simple example of a functional interface is: 


interface Runnable { 
void run(); 


The following interface is not functional because it declares nothing which is not already 
a member of Object: 


interface NonFunc { 
boolean equals (Object obj); 


However, its subinterface can be functional by declaring an abstract method which is 
not a member of Object: 


interface Func extends NonFunc { 
int compare(String ol, String 02); 


Similarly, the well known interface java.util.Comparator<T> is functional because it 
has one abstract non-Object method: 
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interface Comparator<T> { 
boolean equals (Object obj); 
int compare(T ol, T 02); 


The following interface is not functional because while it only declares one abstract 
method which is not a member of Object, it declares two abstract methods which are 
not public members of Object: 


interface Foo { 
int m(); 
Object clone(); 


Example 9.8-2. Functional Interfaces and Erasure 


In the following interface hierarchy, z is a functional interface because while it inherits two 
abstract methods which are not members of Object, they have the same signature, so 
the inherited methods logically represent a single method: 


interface X { int m(Iterable<String> arg); } 
interface Y { int m(Iterable<String> arg); } 
interface Z extends X, Y {} 


Similarly, Z is a functional interface in the following interface hierarchy because Y.m is a 
subsignature of X.m and is return-type-substitutable for x .m: 


interface X { Iterable m(Iterable<String> arg); } 
interface Y { Iterable<String> m(Iterable arg); } 
interface Z extends X, Y {} 


The definition of functional interface respects the fact that an interface cannot have two 
members which are not subsignatures of each other, yet have the same erasure (§9.4.1.2). 
Thus, in the following three interface hierarchies where Z causes a compile-time error, Z 
is not a functional interface: (because none of its abst ract members are subsignatures of 
all other abst ract members) 


interface X int m(Iterable<String> arg); } 
interface Y int m(Iterable<Integer> arg); } 
interface Z extends X, Y {} 


interface X int m(Iterable<String> arg, Class c); } 
interface Y int m(Iterable arg, Class<?> c); } 
interface Z extends X, Y {} 


interface X<T> { void m(T arg); } 
interface Y<T> { void m(T arg); } 
interface Z<A, B> extends X<A>, Y<B> {} 


Similarly, the definition of "functional interface" respects the fact that an interface may 
only have methods with override-equivalent signatures if one is return-type-substitutable 
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for all the others. Thus, in the following interface hierarchy where Z causes a compile-time 
error, Z is not a functional interface: (because none of its abst ract members are return- 
type-substitutable for all other abst ract members) 


interface X { long m(); } 
interface Y { int m(); } 
interface Z extends X, Y {} 


7 
7 


In the following example, the declarations of Foo<T,N> and Bar are legal: in each, the 
methods called m are not subsignatures of each other, but do have different erasures. Still, 
the fact that the methods in each are not subsignatures means Foo<T, N> and Bar are not 
functional interfaces. However, Baz is a functional interface because the methods it inherits 
from Foo<Integer, Integer> have the same signature and so logically represent a single 
method. 


interface Foo<T, N extends Number> { 
void m(T arg) 
void m(N arg) 


7 
’ 


} 
interface Bar extends Foo<String, Integer> {} 
interface Baz extends Foo<Integer, Integer> {} 


Finally, the following examples demonstrate the same rules as above, but with generic 
methods: 


interface Exec { <T> T execute(Action<T> a); } 
// Functional 


interface X { <I> T execute(Action<T> a); } 
interface Y { <S> S execute (Action<S> a); } 
interface Exec extends X, Y {} 

// Functional: signatures are logically "the same" 


interface X { <T> T execute (Action<T> a); } 
interface Y { <S,T> S execute (Action<S> a); } 
interface Exec extends X, Y {} 

// Error: different signatures, same erasure 


Example 9.8-3. Generic Functional Interfaces 


Functional interfaces can be generic, such as java.util.function.Predicate<T>. 
Such a functional interface may be parameterized in a way that produces distinct abstract 
methods - that is, multiple methods that cannot be legally overridden with a single 
declaration. For example: 


interface I { Object m(Class c); } 

interface J<S> { S m(Class<?> c); } 

interface K<T> { T m(Class<?> c); } 

interface Functional<S,T> extends I, J<S>, K<T> {} 
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Functional<s,T> is a functional interface - I.m is return-type-substitutable for J.m 
and K.m - but the functional interface type Functional<String, Integer> clearly 
cannot be implemented with a single method. However, other parameterizations of 
Funct ional<s, T> which are functional interface types are possible. 


The declaration of a functional interface allows a functional interface type to be 
used in a program. There are four kinds of functional interface type: 
¢ The type of a non-generic ($6.1) functional interface 


¢ A parameterized type that is a parameterization (§4.5) of a generic functional 
interface 


¢ The raw type (§4.8) of a generic functional interface 


¢ An intersection type ($4.9) that induces a notional functional interface 


In special circumstances, it is useful to treat an intersection type as a functional interface 
type. Typically, this will look like an intersection of a functional interface type with one 
or more marker interface types, such as Runnable & java.io.Serializable. Such an 
intersection can be used in casts (§15.16) that force a lambda expression to conform to a 
certain type. If one of the interface types in the intersection is java.io.Serializable, 
special run-time support for serialization is triggered (§15.27.4). 


9.9 Function Types 


The function type of a functional interface r is a method type (§8.2) that can be 
used to override (§8.4.8) the abstract method(s) of r. 


Let mu be the set of abstract methods defined for r. The function type of r consists 
of the following: 


¢ Type parameters, formal parameter types, and return type: 
Let m be a method in » with: 
1. a signature that is a subsignature of every method's signature in ; and 


2. areturn type R (possibly void), where either R is the same as every method's 
return type in ™, or R is a reference type and is a subtype of every method's 
return type in m (after adapting for any type parameters (§8.4.4) if the two 
methods have the same signature). 


If no such method exists, then let m be a method in m with: 


1. a signature that is a subsignature of every method's signature in ™; and 
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2. a return type such that m is return-type-substitutable ($8.4.5) for every 
method in m. 


The function type's type parameters, formal parameter types, and return type are 
as given by m. 


* throws Clause: 


The function type's throws clause is derived from the throws clauses of the 
methods in yw, as follows: 


1. If the function type is generic, the throws clauses are first adapted to the 
type parameters of the function type (§8.4.4). 


If the function type is not generic but at least one method in mis generic, the 
throws Clauses are first erased. 


2. Then, the function type’s throws clause includes every type £ which satisfies 
the following constraints: 


— Eis mentioned in one of the throws clauses. 


— For each throws clause, £ is a subtype of some type named in that clause. 


When some return types in ™ are raw and others are not, the definition of a function type 
tries to choose the most specific type, if possible. For example, if the return types are 
LinkedList and LinkedList<String>, then the latter is immediately chosen as the 
function type's return type. When there is no most specific type, the definition compensates 
by finding the most substitutable return type. For example, if there is a third return type, 
List<?>, then it is not the case that one of the return types is a subtype of every other 
(as raw LinkedList is not a subtype of List<?>); instead, LinkedList<String> is 
chosen as the function type's return type because it is return-type-substitutable for both 
LinkedList and List<?>. 


The goal driving the definition of a function type's thrown exception types is to support 
the invariant that a method with the resulting throws clause could override each abstract 
method of the functional interface. Per §8.4.6, this means the function type cannot throw 
"more" exceptions than any single method in the set M, so we look for as many exception 
types as possible that are "covered" by every method's throws clause. 


The function type of a functional interface type is specified as follows: 


¢ The function type of the type of a non-generic functional interface r is simply 
the function type of the functional interface r, as defined above. 


¢ The function type of a parameterized functional interface type r<A;...A,>, where 
A..-An are types and the corresponding type parameters of I are P;...P,, is derived 
by applying the substitution [P;:=A;, ..., Pni=An] to the function type of the 
generic functional interface I<P}...P,>. 
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¢ The function type of a parameterized functional interface type r<A;...A,>, 
where one or more of A;...4, is a wildcard, is the function type of the non- 
wildcard parameterization of I, I<Tj...T;>. The non-wildcard parameterization 
is determined as follows. 


Let P;...P, be the type parameters of r with corresponding bounds 28)...B,. For all 
i(1 <i<n), T; is derived according to the form of a;: 


— If a; is atype, then T; = a,. 


— If a; is a wildcard, and the corresponding type parameter's bound, B;, mentions 
one of P;...P,, then 7; is undefined and there is no function type. 


— Otherwise: 
> If a; is an unbound wildcard ?, then 7; = B;. 


>» If a; is a upper-bounded wildcard ? extends u,, then T; = glb(v:, B,) 
(§5.1.10). 


> If a; is a lower-bounded wildcard ? super L,;, then T; = L;. 


¢ The function type of the raw type of a generic functional interface r<...> is the 
erasure of the function type of the generic functional interface r<...>. 


¢ The function type of an intersection type that induces a notional functional 
interface is the function type of the notional functional interface. 


Example 9.9-1. Function Types 


Given the following interfaces: 


interface X { void m() throws IOException; } 
interface Y { void m() throws EOFException; } 
interface Z { void m() throws ClassNotFoundException; } 


the function type of: 

interface XY extends X, Y {} 
is: 

()->void throws EOFException 
while the function type of: 

interface XYZ extends X, Y, Z {} 


is: 
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()->void (throws nothing) 
Given the following interfaces: 


interface A { 
List<String> foo(List<String> arg) 
throws IOException, SQLTransientException; 
} 
interface B { 
List foo(List<String> arg) 
throws EOFException, SQLException, TimeoutException; 
} 
interface C { 
List foo(List arg) throws Exception; 


the function type of: 
interface D extends A, B {} 
is: 


(List<String>) ->List<String> 
throws EOFException, SQLTransientException 


while the function type of: 
interface E extends A, B, C {} 
is: 
(List)->List throws EOFException, SQLTransientException 


The function type of a functional interface is defined nondeterministically: while the 
signatures in Mare "the same", they may be syntactically different (HashMap. Entry and 
Map.Entry, for example); the return type may be a subtype of every other return type, but 
there may be other return types that are also subtypes (List<?> and List<? extends 
Object>, for example); and the order of thrown types is unspecified. These distinctions 
are subtle, but they can sometimes be important. However, function types are not used 
in the Java programming language in such a way that the nondeterminism matters. Note 
that the return type and throws clause of a "most specific method" are also defined 
nondeterministically when there are multiple abstract methods (§15.12.2.5). 


When a generic functional interface is parameterized by wildcards, there are many 
different instantiations that could satisfy the wildcard and produce different function types. 
For example, each of Predicate<Integer> (function type Integer -> boolean), 
Predicate<Number> (function type Number -> boolean), and Predicate<Object> 
(function type Object -> boolean)isaPredicate<? super Integer>. Sometimes, it 
is possible to known from the context, such as the parameter types of a lambda expression, 
which function type is intended (§15.27.3). Other times, it is necessary to pick one; in 
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these circumstances, the bounds are used. (This simple strategy cannot guarantee that the 
resulting type will satisfy certain complex bounds, so not all complex cases are supported.) 


Example 9.9-2. Generic Function Types 


A function type may be generic, as a functional interface's abstract method may be generic. 
For example, in the following interface hierarchy: 


interface Gl { 
<E extends Exception> Object m() throws E; 


} 


interface G2 { 
<F extends Exception> String m() throws Exception; 


} 
interface G extends Gl, G2 {} 


the function type of G is: 
<F extends Exception> ()->String throws F 


A generic function type for a functional interface may be implemented by a method 


reference expression (§15.13), but not by a lambda expression (§15.27) as there is no syntax 
for generic lambda expressions. 
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Arrays 


Ix the Java programming language, arrays are objects (§4.3.1), are dynamically 
created, and may be assigned to variables of type object (§4.3.2). All methods of 
class Object may be invoked on an array. 


An array object contains a number of variables. The number of variables may be 
zero, in which case the array is said to be empty. The variables contained in an 
array have no names; instead they are referenced by array access expressions that 
use non-negative integer index values. These variables are called the components 
of the array. If an array has n components, we say n is the length of the array; 
the components of the array are referenced using integer indices from 0 to n - 1, 
inclusive. 


All the components of an array have the same type, called the component type of 
the array. If the component type of an array is 7, then the type of the array itself 
is written T[]. 


The value of an array component of type float is always an element of the float 
value set (§4.2.3); similarly, the value of an array component of type double is 
always an element of the double value set. It is not permitted for the value of an 
array component of type float to be an element of the float-extended-exponent 
value set that is not also an element of the float value set, nor for the value of an 
array component of type double to be an element of the double-extended-exponent 
value set that is not also an element of the double value set. 


The component type of an array may itself be an array type. The components 
of such an array may contain references to subarrays. If, starting from any array 
type, one considers its component type, and then (if that is also an array type) the 
component type of that type, and so on, eventually one must reach a component 
type that is not an array type; this is called the element type of the original array, 
and the components at this level of the data structure are called the elements of the 
original array. 
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There are some situations in which an element of an array can be an array: if the 
element type is Object Or Cloneable Or java.io.Serializable, then some or all 
of the elements may be arrays, because any array object can be assigned to any 
variable of these types. 


10.1 Array Types 


Atray types are used in declarations and in cast expressions ($15.16). 


An array type is written as the name of an element type followed by some number 
of empty pairs of square brackets []. The number of bracket pairs indicates the 
depth of array nesting. 


Each bracket pair in an array type may be annotated by type annotations (§9.7.4). 
An annotation applies to the bracket pair (or ellipsis, in a variable arity parameter 
declaration) that follows it. 


The element type of an array may be any type, whether primitive or reference. In 
particular: 


e Arrays with an interface type as the element type are allowed. 


An element of such an array may have as its value a null reference or an instance 
of any type that implements the interface. 


¢ Arrays with an abstract class type as the element type are allowed. 


An element of such an array may have as its value a null reference or an instance 
of any subclass of the abstract class that is not itself abstract. 


An array's length is not part of its type. 


The supertypes of an array type are specified in §4.10.3. 


The supertype relation for array types is not the same as the superclass relation. The direct 
supertype of Integer[] is Number[] according to §4.10.3, but the direct superclass of 
Integer[] is Object according to the Class object for Integer[] (§10.8). This does 
not matter in practice, because Object is also a supertype of all array types. 


10.2 Array Variables 


A variable of array type holds a reference to an object. Declaring a variable of array 
type does not create an array object or allocate any space for array components. It 
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creates only the variable itself, which can contain a reference to an array. However, 
the initializer part of a declarator (§8.3, $9.3, §14.4.1) may create an array, a 
reference to which then becomes the initial value of the variable. 


Example 10.2-1. Declarations of Array Variables 


int [] ai; // array of int 
short[][] as; // array of array of short 
short Ss, // scalar short 
aas[][]; // array of array of short 
Object[] ao, // array of Object 
otherAo; // array of Object 
Collection<?>[] ca; // array of Collection of unknown type 


The declarations above do not create array objects. The following are examples of 
declarations of array variables that do create array objects: 


Exception ae[] = new Exception[3]; 

Object aao[][] = new Exception[2] [3]; 

int[] factorial = { 1, 1, 2, 6, 24, 120, 720, 5040 }; 

char ac[] SS ffs erat OO a EM at We Me 
Ss, piss el her lees Tat, 'g' he 


String[] aas f- "array", - "OL", “"String™,. 1; 


The array type of a variable depends on the bracket pairs that may appear as part of 
the type at the beginning of a variable declaration, or as part of the declarator for 
the variable, or both. Specifically, in the declaration of a field, formal parameter, 
or local variable (§8.3, §8.4.1, $9.3, $9.4, §14.4.1, §14.14.2, $15.27.1), the array 
type of the variable is denoted by: 


¢ the element type that appears at the beginning of the declaration; then, 


¢ any bracket pairs that follow the variable's Identifier in the declarator (not 
applicable for a variable arity parameter); then, 


¢ any bracket pairs that appear in the type at the beginning of the declaration (where 
the ellipsis of a variable arity parameter is treated as a bracket pair). 


The return type of a method (§8.4.5) may be an array type. The precise array type 
depends on the bracket pairs that may appear as part of the type at the beginning 
of the method declaration, or after the method's formal parameter list, or both. The 
array type is denoted by: 


¢ the element type that appears in the Result; then, 
¢ any bracket pairs that follow the formal parameter list; then, 


¢ any bracket pairs that appear in the Result. 
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Array Variables 


We do not recommend "mixed notation" in array variable declarations, 


ARRAYS 


where 


bracket pairs appear on both the type and in declarators; nor in method declarations, 


where bracket pairs appear both before and after the formal parameter list. 


Example 10.2-2. Array Variables and Array Types 
The local variable declaration statement: 

byte[] rowvector, colvector, matrix[]; 
is equivalent to: 


byte rowvector[], colvector[], matrix[][]; 


because the array type of each local variable is unchanged. Similarly, the local variable 


declaration statement: 
int a, bli], cll; 

is equivalent to the series of declaration statements: 
int a; 


int[] b; 
int[][] c; 


Brackets are allowed in declarators as a nod to the tradition of C and C++. The general 
rules for variable declaration, however, permit brackets to appear on both the type and in 


declarators, so that the local variable declaration statement: 
float[][] ffl], gflflll], hll; // Yechh! 
is equivalent to the series of declarations: 


float[][][](] f; 
float[][][]f1[] oF 
float[][1][] h; 


Because of how array types are formed, the following parameter declarations have the same 


array type: 
void m(int @A [] @B [] x) {} 
void n(int @A [] @B ... y) {} 


And perhaps surprisingly, the following field declarations have the same array type: 


int @A [] f @B []; 
int @B [] @A [] g; 


ARRAYS Array Creation 


Once an array object is created, its length never changes. To make an array variable 
refer to an array of different length, a reference to a different array must be assigned 
to the variable. 


A single variable of array type may contain references to arrays of different lengths, 
because an array's length is not part of its type. 


If an array variable v has type al], where a is a reference type, then v can hold 
a reference to an instance of any array type B[], provided B can be assigned to a 
($5.2). This may result in a run-time exception on a Jater assignment; see §10.5 
for a discussion. 


10.3 Array Creation 


An array is created by an array creation expression (§15.10.1) or an array initializer 
($10.6). 


An array creation expression specifies the element type, the number of levels of 
nested arrays, and the length of the array for at least one of the levels of nesting. 
The array's length is available as a final instance variable length. 


An array initializer creates an array and provides initial values for all its 
components. 


10.4 Array Access 


A component of an array is accessed by an array access expression (§15.10.3) that 
consists of an expression whose value is an array reference followed by an indexing 
expression enclosed by [ and ], as in A[il]. 


All arrays are 0-origin. An array with length n can be indexed by the integers 0 
to n-1. 


Example 10.4-1. Array Access 


class Gauss { 
public static void main(String[] args) { 


int[] ia = new int[101]; 

for (int i = 0; i < ia.length; i++) ia[i] = i; 
int sum = 0; 

for (int e : ia) sum += e; 


System.out.printlin(sum) ; 
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This program produces the output: 
5050 


The program declares a variable ia that has type array of int, that is, int []. The variable 
ia is initialized to reference a newly created array object, created by an array creation 
expression (§15.10.1). The array creation expression specifies that the array should have 
101 components. The length of the array is available using the field length, as shown. 
The program fills the array with the integers from 0 to 100, sums these integers, and prints 
the result. 


Arrays must be indexed by int values; short, byte, or char values may also 
be used as index values because they are subjected to unary numeric promotion 
(§5.6.1) and become int values. 


An attempt to access an array component with a long index value results in a 
compile-time error. 


All array accesses are checked at run time; an attempt to use an index that 
is less than zero or greater than or equal to the length of the array causes an 
ArrayIndexOutOfBoundsException to be thrown (§15.10.4). 


10.5 Array Store Exception 


For an array whose type is a[], where a is a reference type, an assignment to 
a component of the array is checked at run time to ensure that the value being 
assigned is assignable to the component. 


If the type of the value being assigned is not assignment-compatible (§5.2) with 
the component type, an ArrayStoreException is thrown. 


If the component type of an array were not reifiable (§4.7), the Java Virtual Machine could 
not perform the store check described in the preceding paragraph. This is why an array 
creation expression with a non-reifiable element type is forbidden (§15.10.1). One may 
declare a variable of an array type whose element type is non-reifiable, but assignment of 
the result of an array creation expression to the variable will necessarily cause an unchecked 
warning (§5.1.9). 


Example 10.5-1. ArrayStoreException 


class Point { int x, y; } 
class ColoredPoint extends Point { int color; } 
class Test { 

public static void main(String[] args) { 


ARRAYS Array Initializers 


ColoredPoint[] cpa = new ColoredPoint [10]; 
Point[] pa = cpa; 
System.out.println(pa[1] == null); 
try { 
pa[0] = new Point (); 


} catch (ArrayStoreException e) { 
System.out.printin(e); 


This program produces the output: 


true 
java.lang.ArrayStoreException: Point 


The variable pa has type Point [] and the variable cpa has as its value a reference to an 
object of type ColoredPoint []. AColoredPoint can be assigned to a Point; therefore, 
the value of cpa can be assigned to pa. 


A reference to this array pa, for example, testing whether pa[1] is nu11, will not result in 
a run-time type error. This is because the element of the array of type ColoredPoint [] 
isa ColoredPoint, and every ColoredPoint can stand in for a Point, since Point is 
the superclass of ColoredPoint. 


On the other hand, an assignment to the array pa can result in a run-time error. At compile 
time, an assignment to an element of pa is checked to make sure that the value assigned is a 
Point. But since pa holds a reference to an array of ColoredPoint, the assignment is valid 
only if the type of the value assigned at run time is, more specifically, a ColoredPoint. 


The Java Virtual Machine checks for such a situation at run time to ensure that the 
assignment is valid; if not, an ArrayStoreException is thrown. 


10.6 Array Initializers 


An array initializer may be specified in a field declaration (§8.3, $9.3) or local 
variable declaration (§14.4), or as part of an array creation expression (§15.10.1), 
to create an array and provide some initial values. 


Arraylnitializer: 
{ [VariablelnitializerList] [, ] } 


VariablelnitializerList: 
Variablelnitializer {, VariableInitializer} 


The following production from §8.3 is shown here for convenience: 
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VariableInitializer: 
Expression 
Arraylnitializer 


An array initializer is written as a comma-separated list of expressions, enclosed 
by braces { and }. 


A trailing comma may appear after the last expression in an array initializer and 
is ignored. 


Each variable initializer must be assignment-compatible ($5.2) with the array's 
component type, or a compile-time error occurs. 


It is a compile-time error if the component type of the array being initialized is not 
reifiable (§4.7). 


The length of the array to be constructed is equal to the number of variable 
initializers immediately enclosed by the braces of the array initializer. Space is 
allocated for a new array of that length. If there is insufficient space to allocate 
the array, evaluation of the array initializer completes abruptly by throwing an 
OutOfMemoryError. Otherwise, a one-dimensional array is created of the specified 
length, and each component of the array is initialized to its default value ($4.12.5). 


The variable initializers immediately enclosed by the braces of the array initializer 
are then executed from left to right in the textual order they occur in the source 
code. The n'th variable initializer specifies the value of the n-1'th array component. 
If execution of a variable initializer completes abruptly, then execution of the array 
initializer completes abruptly for the same reason. If all the variable initializer 
expressions complete normally, the array initializer completes normally, with the 
value of the newly initialized array. 


If the component type is an array type, then the variable initializer specifying a 
component may itself be an array initializer; that is, array initializers may be nested. 
In this case, execution of the nested array initializer constructs and initializes an 
array object by recursive application of the algorithm above, and assigns it to the 
component. 


Example 10.6-1. Array Initializers 


class Test { 
public static void main(String[] args) { 
int ia[][] = { {1, 2}, null }; 
for (int[] ea : ia) { 
for (int e: ea) { 
System.out.printin(e); 


} 


ARRAYS Array Members 


This program produces the output: 


before causing a Nul1PointerException in trying to index the second component of the 
array ia, which is a null reference. 


10.7 Array Members 


The members of an array type are all of the following: 


e The public final field Length, which contains the number of components of 
the array. length may be positive or zero. 


e¢ The public method clone, which overrides the method of the same name in 
class object and throws no checked exceptions. The return type of the clone 
method of an array type T[] is T[]. 


A clone of a multidimensional array is shallow, which is to say that it creates 
only a single new array. Subarrays are shared. 


e All the members inherited from class object; the only method of object that is 
not inherited is its clone method. 


See §9.6.4.4 for another situation where the difference between publicandnon-public 
methods of Object requires special care. 


An array thus has the same public fields and methods as the following class: 


class A<T> implements Cloneable, java.io.Serializable { 
public final int length = X; 
public T[] clone() { 
try { 
return (T[])super.clone(); 
} catch (CloneNotSupportedException e) { 
throw new InternalError(e.getMessage()); 


} 
} 


Note that the cast to T[] in the code above would generate an unchecked warning (§5.1.9) 
if arrays were really implemented this way. 
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Example 10.7-1. Arrays Are Cloneable 


class Testl { 
public static void main(String[] args) { 
int ial[] = { 1, 2 }; 


int ia2[] = ial.clone(); 
System.out.print((ial == ia2) + " "); 
ial[1]++; 


System.out.println(ia2[1]); 


This program produces the output: 
false 2 


showing that the components of the arrays referenced by ial and ia2 are different 
variables. 


Example 10.7-2. Shared Subarrays After A Clone 


The fact that subarrays are shared when a multidimensional array is cloned is shown by 
this program: 


class Test2 { 
public static void main(String[] args) throws Throwable { 


int iaf]{[] = { {1,2}, null }; 

int jal][] = ia.clone(); 

System.out.print((ia == ja) +" "); 
System.out.printlin(ia[0] == ja[0] && ia[1l] == ja[1]); 


This program produces the output: 
false true 


showing that the int [] array that is ia[0] and the int [] array that is ja[0] are the same 
array. 


10.8 class Objects for Arrays 
Every array has an associated class object, shared with all other arrays with the 


same component type. 


Although an array type is not a class, the class object of every array acts as if: 
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¢ The direct superclass of every array type is Object. 


e Every array type implements the interfaces Cloneable and 


java.io.Serializable. 


Example 10.8-1. class Object Of Array 


class Testl { 
public static void main(String[] args) { 


int[{] ia = new int[3]; 
System.out.printiln(ia.getClass()); 
System.out.printin(ia.getClass().getSuperclass()); 
for (Class<?> c : ia.getClass().getInterfaces() ) 
System.out.println("Superinterface: " + c); 


This program produces the output: 


class [I 

class java.lang.Object 

Superinterface: interface java.lang.Cloneable 
Superinterface: interface java.io.Serializable 


where the string "[I" is the run-time type signature for the Class object "array with 
component type int”. 


Example 10.8-2. Array class Objects Are Shared 


class Test2 { 
public static void main(String[] args) { 


int[{] ia = new int[3]; 

int[] ib = new int[6]; 

System.out.println(ia == ib); 
System.out.println(ia.getClass() == ib.getClass()); 


This program produces the output: 


false 
true 


While ia and ib refer to different arrays, the result of the comparison of the Class objects 


demonstrates that all arrays whose components are of type int are instances of the same 
array type (namely int []). 
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10.9 An Array of Characters Is Not a string 


In the Java programming language, unlike C, an array of char is not a String, 
and neither a String nor an array of char is terminated by '\uo000' (the NUL 
character). 


A String object is immutable, that is, its contents never change, while an array of 
char has mutable elements. 


The method toCharArray in class String returns an array of characters containing 
the same character sequence as a String. The class StringBuffer implements useful 
methods on mutable arrays of characters. 


CHAPTER 11 


Exceptions 


\ \ HEN a program violates the semantic constraints of the Java programming 
language, the Java Virtual Machine signals this error to the program as an 
exception. 


An example of such a violation is an attempt to index outside the bounds of an 
array. Some programming languages and their implementations react to such errors 
by peremptorily terminating the program; other programming languages allow an 
implementation to react in an arbitrary or unpredictable way. Neither of these 
approaches is compatible with the design goals of the Java SE Platform: to provide 
portability and robustness. 


Instead, the Java programming language specifies that an exception will be thrown 
when semantic constraints are violated and will cause a non-local transfer of control 
from the point where the exception occurred to a point that can be specified by the 
programmer. 


An exception is said to be thrown from the point where it occurred and is said to 
be caught at the point to which control is transferred. 


Programs can also throw exceptions explicitly, using throw statements (§14.18). 


Explicit use of throw statements provides an alternative to the old-fashioned style 
of handling error conditions by returning funny values, such as the integer value 
-1 where a negative value would not normally be expected. Experience shows that 
too often such funny values are ignored or not checked for by callers, leading to 
programs that are not robust, exhibit undesirable behavior, or both. 


Every exception is represented by an instance of the class Throwable or one of its 
subclasses (§11.1). Such an object can be used to carry information from the point 
at which an exception occurs to the handler that catches it. Handlers are established 
by catch clauses of try statements (§14.20). 
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During the process of throwing an exception, the Java Virtual Machine abruptly 
completes, one by one, any expressions, statements, method and constructor 
invocations, initializers, and field initialization expressions that have begun but not 
completed execution in the current thread. This process continues until a handler is 
found that indicates that it handles that particular exception by naming the class of 
the exception or a superclass of the class of the exception ($11.2). Ifno such handler 
is found, then the exception may be handled by one of a hierarchy of uncaught 
exception handlers ($11.3) - thus every effort is made to avoid letting an exception 
go unhandled. 


The exception mechanism of the Java SE Platform is integrated with its 
synchronization model (§17.1), so that monitors are unlocked as synchronized 
statements (§14.19) and invocations of synchronized methods (§8.4.3.6, $15.12) 
complete abruptly. 


11.1 The Kinds and Causes of Exceptions 


11.1.1 The Kinds of Exceptions 


An exception is represented by an instance of the class Throwable (a direct subclass 
of Object) or one of its subclasses. 


Throwable and all its subclasses are, collectively, the exception classes. 


The classes Exception and Error are direct subclasses of Throwable: 


* Exception is the superclass of all the exceptions from which ordinary programs 
may wish to recover. 


The class RuntimeException is a direct subclass of Exception. 
Runt imeException is the superclass of all the exceptions which may be thrown 
for many reasons during expression evaluation, but from which recovery may 
still be possible. 


Runt imeException and all its subclasses are, collectively, the run-time exception 
classes. 


* Error is the superclass of all the exceptions from which ordinary programs are 
not ordinarily expected to recover. 


Error and all its subclasses are, collectively, the error classes. 


The unchecked exception classes are the run-time exception classes and the error 
classes. 


EXCEPTIONS 


The Kinds and Causes of Exceptions 


The checked exception classes are all exception classes other than the unchecked 
exception classes. That is, the checked exception classes are Throwable and all 
its subclasses other than RuntimeException and its subclasses and Error and its 


subclasses. 


Programs can use the pre-existing exception classes of the Java SE Platform API in throw 
statements, or define additional exception classes as subclasses of Throwable or of any of 
its subclasses, as appropriate. To take advantage of compile-time checking for exception 
handlers (§11.2), it is typical to define most new exception classes as checked exception 
classes, that is, as subclasses of Exception that are not subclasses of Runt imeException. 


The class Error is a separate subclass of Throwabl1e, distinct from Except ion in the class 


hierarchy, to allow programs to use the idiom"} catc 
to catch all exceptions from which recovery may be pos 
which recovery is typically not possible. 


h (Exception e) {" (§11.2.3) 
sible without catching errors from 


Note that a subclass of Throwable cannot be generic (§8.1.2). 


11.1.2 The Causes of Exceptions 


An exception is thrown for one of three reasons: 


e A throw statement (§14.18) was executed. 


e An abnormal execution condition was synchronously detected by the Java 


Virtual Machine, namely: 


— evaluation of an expression violates the normal semantics of the Java 
programming language ($15.6), such as an integer divide by zero. 


— an error occurs while loading, linking, or i 


nitializing part of the program 


(§12.2, §12.3, §12.4); in this case, an instance of a subclass of LinkageError 


is thrown. 


— an internal error or resource limitation prevents the Java Virtual Machine from 
implementing the semantics of the Java programming language; in this case, 


an instance of a subclass of virtualMachinel 


Error is thrown. 


These exceptions are not thrown at an arbitrary point in the program, but rather at 
a point where they are specified as a possible result of an expression evaluation 


or statement execution. 


¢ An asynchronous exception occurred (§11.1.3). 
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11.1.3. Asynchronous Exceptions 


Most exceptions occur synchronously as a result of an action by the thread in which 
they occur, and at a point in the program that is specified to possibly result in such 
an exception. An asynchronous exception is, by contrast, an exception that can 
potentially occur at any point in the execution of a program. 


Asynchronous exceptions occur only as a result of: 
¢ An invocation of the (deprecated) stop method of class Thread or ThreadGroup. 


The (deprecated) stop methods may be invoked by one thread to affect another 
thread or all the threads in a specified thread group. They are asynchronous 
because they may occur at any point in the execution of the other thread or 
threads. 


¢ An internal error or resource limitation in the Java Virtual Machine that prevents 
it from implementing the semantics of the Java programming language. In this 
case, the asynchronous exception that is thrown is an instance of a subclass of 


VirtualMachineError. 


Note that StackOverflowError, a subclass of VirtualMachineError, may be 
thrown synchronously by method invocation (§15.12.4.5) as well as asynchronously 
due to native method execution or Java Virtual Machine resource limitations. 
Similarly, OutOfMemoryError, another subclass of VirtualMachineError, may be 
thrown synchronously during class instance creation (§15.9.4, §12.5), array creation 
(§15.10.2, §10.6), class initialization (§12.4.2), and boxing conversion (§5.1.7), as well 
as asynchronously. 


The Java SE Platform permits a small but bounded amount of execution to occur 
before an asynchronous exception is thrown. 


Asynchronous exceptions are rare, but proper understanding of their semantics is necessary 
if high-quality machine code is to be generated. 


The delay noted above is permitted to allow optimized code to detect and throw these 
exceptions at points where it is practical to handle them while obeying the semantics of 
the Java programming language. A simple implementation might poll for asynchronous 
exceptions at the point of each control transfer instruction. Since a program has a finite 
size, this provides a bound on the total delay in detecting an asynchronous exception. Since 
no asynchronous exception will occur between control transfers, the code generator has 
some flexibility to reorder computation between control transfers for greater performance. 
The paper Polling Efficiently on Stock Hardware by Marc Feeley, Proc. 1993 Conference 
on Functional Programming and Computer Architecture, Copenhagen, Denmark, pp. 
179-187, is recommended as further reading. 
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11.2 Compile-Time Checking of Exceptions 


The Java programming language requires that a program contains handlers for 
checked exceptions which can result from execution of a method or constructor 
($8.4.6, §8.8.5). This compile-time checking for the presence of exception handlers 
is designed to reduce the number of exceptions which are not properly handled. For 
each checked exception which is a possible result, the throws clause for the method 
or constructor must mention the class of that exception or one of the superclasses 
of the class of that exception (§11.2.3). 


The checked exception classes (§11.1.1) named in the throws clause are part of 
the contract between the implementor and user of the method or constructor. The 
throws Clause of an overriding method may not specify that this method will result 
in throwing any checked exception which the overridden method is not permitted, 
by its throws clause, to throw (§8.4.8.3). When interfaces are involved, more than 
one method declaration may be overridden by a single overriding declaration. In 
this case, the overriding declaration must have a throws clause that is compatible 
with all the overridden declarations (§9.4.1). 


The unchecked exception classes (§11.1.1) are exempted from compile-time 
checking. 


Error classes are exempted because they can occur at many points in the program and 
recovery from them is difficult or impossible. A program declaring such exceptions would 
be cluttered, pointlessly. Sophisticated programs may yet wish to catch and attempt to 
recover from some of these conditions. 


Run-time exception classes are exempted because, in the judgment of the designers of the 
Java programming language, having to declare such exceptions would not aid significantly 
in establishing the correctness of programs. Many of the operations and constructs of the 
Java programming language can result in exceptions at run time. The information available 
to a Java compiler, and the level of analysis a compiler performs, are usually not sufficient 
to establish that such run-time exceptions cannot occur, even though this may be obvious 
to the programmer. Requiring such exception classes to be declared would simply be an 
irritation to programmers. 


For example, certain code might implement a circular data structure that, by construction, 
can never involve null references; the programmer can then be certain that a 
NullPointerException cannot occur, but it would be difficult for a Java compiler to 
prove it. The theorem-proving technology that is needed to establish such global properties 
of data structures is beyond the scope of this specification. 


We say that a statement or expression can throw an exception class E if, according 
to the rules in §11.2.1 and §11.2.2, the execution of the statement or expression 
can result in an exception of class £ being thrown. 


11.2 


365 


11.2 


366 


Compile-Time Checking of Exceptions EXCEPTIONS 


We say that a catch clause can catch its catchable exception class(es): 


¢ The catchable exception class of a uni-catch clause is the declared type of its 
exception parameter ($14.20). 


¢ The catchable exception classes of a multi-catch clause are the alternatives in 
the union that denotes the type of its exception parameter. 


11.2.1 Exception Analysis of Expressions 


A class instance creation expression (§15.9) can throw an exception class =£ iff 
either: 


e« The expression is a qualified class instance creation expression and the 
qualifying expression can throw £; or 


¢ Some expression of the argument list can throw £; or 


¢ Eis one of the exception types of the invocation type of the chosen constructor 
($15.12.2.6); or 


¢ The class instance creation expression includes a ClassBody, and some instance 
initializer or instance variable initializer in the ClassBody can throw E. 


A method invocation expression ($15.12) can throw an exception class £ iff either: 


¢ The method invocation expression is of the form Primary . [TypeArguments] 
Identifier and the Primary expression can throw £; or 


¢ Some expression of the argument list can throw £; or 


¢ £ is one of the exception types of the invocation type of the chosen method 
($15.12.2.6). 


A lambda expression ($15.27) can throw no exception classes. 


For every other kind of expression, the expression can throw an exception class £ 
iff one of its immediate subexpressions can throw E. 


Note that a method reference expression (§15.13) of the form Primary : : [TypeArguments] 
Identifier can throw an exception class if the Primary subexpression can throw an 
exception class. In contrast, a lambda expression can throw nothing, and has no immediate 
subexpressions on which to perform exception analysis. It is the body of a lambda 
expression, containing expressions and statements, that can throw exception classes. 


EXCEPTIONS Compile-Time Checking of Exceptions 


11.2.2 Exception Analysis of Statements 


A throw Statement ($14.18) whose thrown expression has static type E and is not 
a final or effectively final exception parameter can throw £ or any exception class 
that the thrown expression can throw. 


For example, the statement throw new java.io.FileNotFoundException(); can 
throw java.io.FileNotFoundException only. Formally, it is not the case that it "can 
throw" a subclass or superclass of java.io.FileNotFoundException. 


A throw Statement whose thrown expression is a final or effectively final exception 
parameter of a catch clause c can throw an exception class £ iff: 


* Eis an exception class that the try block of the try statement which declares 
c can throw; and 


* Eis assignment compatible with any of c's catchable exception classes; and 


¢ Eis not assignment compatible with any of the catchable exception classes of the 
catch Clauses declared to the left of cin the same try statement. 


A try statement (§14.20) can throw an exception class £ iff either: 


¢ The try block can throw £, or an expression used to initialize a resource (in a 
try-with-resources statement) can throw £, or the automatic invocation of the 
close() method of a resource (in a try-with-resources statement) can throw E£, 
and £ is not assignment compatible with any catchable exception class of any 
catch Clause of the try statement, and either no finally block is present or the 
finally block can complete normally; or 


¢ Some catch block of the try statement can throw £ and either no finally block 
is present or the finally block can complete normally; or 


¢ A finally block is present and can throw E. 


An explicit constructor invocation statement (§8.8.7.1) can throw an exception 
class £ iff either: 


¢ Some expression of the constructor invocation's parameter list can throw £; or 


¢ £ is determined to be an exception class of the throws clause of the constructor 
that is invoked (§15.12.2.6). 


Any other statement S can throw an exception class £ iff an expression or statement 
immediately contained in S can throw E. 
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11.2.3. Exception Checking 


It is a compile-time error if a method or constructor body can throw some exception 
class £ when E£ is a checked exception class and £ is not a subclass of some class 
declared in the throws clause of the method or constructor. 


It is a compile-time error if a lambda body can throw some exception class F when 
Eis achecked exception class and £ is not a subclass of some class declared in the 
throws Clause of the function type targeted by the lambda expression. 


It is a compile-time error if a class variable initializer (§8.3.2) or static initializer 
($8.7) of a named class or interface can throw a checked exception class. 


It is a compile-time error if an instance variable initializer (§8.3.2) or instance 
initializer ($8.6) of a named class can throw a checked exception class, unless 
the named class has at least one explicitly declared constructor and the exception 
class or one of its superclasses is explicitly declared in the throws clause of each 
constructor. 


Note that no compile-time error is due if an instance variable initializer or instance initializer 
of an anonymous class (§15.9.5) can throw an exception class. In a named class, it is 
the responsibility of the programmer to propagate information about which exception 
classes can be thrown by initializers, by declaring a suitable throws clause on any explicit 
constructor declaration. This relationship between the checked exception classes thrown 
by aclass's initializers and the checked exception classes declared by a class's constructors 
is assured for an anonymous class declaration, because no explicit constructor declarations 
are possible and a Java compiler always generates a constructor with a suitable throws 
clause for the anonymous class declaration based on the checked exception classes that its 
initializers can throw. 


It is a compile-time error if a catch clause can catch checked exception class £; 
and it is not the case that the try block corresponding to the catch clause can 
throw a checked exception class that is a subclass or superclass of £,, unless £; is 
Exception or a superclass of Exception. 


It is a compile-time error if a catch clause can catch an exception class £, and a 
preceding catch clause of the immediately enclosing try statement can catch E, 
or a superclass of £;. 


A Java compiler is encouraged to issue a warning if a catch clause can catch checked 
exception class £, and the try block corresponding to the cat ch clause can throw checked 
exception class Ez, where E2 <: E;, and a preceding catch clause of the immediately 
enclosing try statement can catch checked exception class E3, where Ep <: E3<: Ej. 


Example 11.2.3-1. Catching Checked Exceptions 


import java.io.*; 
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class StaticallyThrownExceptionsIncludeSubtypes { 
public static void main(String[] args) { 
try { 
throw new FileNotFoundException(); 
} catch (IOException ioe) { 
// “catch IOException" catches IOException 
// and any subtype. 


try { 
throw new FileNotFoundException() ; 
// Statement "can throw" FileNotFoundException. 
// It is not the case that statement "can throw" 
// a subtype or supertype of FileNotFoundException. 
} catch (FileNotFoundException fnfe) { 
// ... Handle exception ... 
} catch (IOException ioe) { 
// Legal, but compilers are encouraged to give 
// warnings as of Java SE 7, because all subtypes of 
// IOException that the try block "can throw" have 
// already been caught by the prior catch clause. 


try { 
m(); 
// m's declaration says "throws IOException", so 
// m "can throw" IOException. It is not the case 
// that m "can throw" a subtype or supertype of 
// IOException (e.g. Exception). 
catch (FileNotFoundException fnfe) { 
// Legal, because the dynamic type of the exception 
// might be FileNotFoundException. 
catch (IOException ioe) { 
// Legal, because the dynamic type of the exception 
// might be a different subtype of IOException. 
catch (Throwable t) { 
// Can always catch Throwable. 


static void m() throws IOException { 
throw new FileNotFoundException(); 


By the rules above, each alternative in a multi-cat ch clause (§14.20) must be able to catch 
some exception class thrown by the try block and uncaught by previous catch clauses. 
For example, the second catch clause below would cause a compile-time error because 
exception analysis determines that SubclassOfFoo is already caught by the first catch 
clause: 


11.2 


369 


11.3 


370 


Run-Time Handling of an Exception EXCEPTIONS 


try { ... } 
Catch (Roo fy fxae J 
catch (Bar | SubclassOfFroo ¢€) { «s+ +} 


11.3. Run-Time Handling of an Exception 


When an exception is thrown (§14.18), control is transferred from the code that 
caused the exception to the nearest dynamically enclosing catch clause, if any, of 
atry statement ($14.20) that can handle the exception. 


A statement or expression is dynamically enclosed by a catch clause if it appears 
within the try block of the try statement of which the catch clause is a part, or 
if the caller of the statement or expression is dynamically enclosed by the catch 
clause. 


The caller of a statement or expression depends on where it occurs: 


¢ If within a method, then the caller is the method invocation expression ($15.12) 
that was executed to cause the method to be invoked. 


¢ If within a constructor or an instance initializer or the initializer for an instance 
variable, then the caller is the class instance creation expression (§15.9) or the 
method invocation of newInstance that was executed to cause an object to be 
created. 


¢ If within a static initializer or an initializer for a static variable, then the caller 
is the expression that used the class or interface so as to cause it to be initialized 
($12.4). 


Whether a particular catch clause can handle an exception is determined by 
comparing the class of the object that was thrown to the catchable exception classes 
of the catch clause. The catch clause can handle the exception if one of its 
catchable exception classes is the class of the exception or a superclass of the class 
of the exception. 


Equivalently, a catch clause will catch any exception object that is an instanceof 
($15.20.2) one of its catchable exception classes. 


The control transfer that occurs when an exception is thrown causes abrupt 
completion of expressions (§15.6) and statements (§14.1) until a catch clause is 
encountered that can handle the exception; execution then continues by executing 
the block of that catch clause. The code that caused the exception is never resumed. 
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All exceptions (synchronous and asynchronous) are precise: when the transfer of 
control takes place, all effects of the statements executed and expressions evaluated 
before the point from which the exception is thrown must appear to have taken 
place. No expressions, statements, or parts thereof that occur after the point from 
which the exception is thrown may appear to have been evaluated. 


If optimized code has speculatively executed some of the expressions or statements which 
follow the point at which the exception occurs, such code must be prepared to hide this 
speculative execution from the user-visible state of the program. 


Ifno catch clause that can handle an exception can be found, then the current thread 
(the thread that encountered the exception) is terminated. Before termination, all 
finally clauses are executed and the uncaught exception is handled according to 
the following rules: 


¢ If the current thread has an uncaught exception handler set, then that handler is 
executed. 


¢ Otherwise, the method uncaughtException is invoked for the ThreadGroup 
that is the parent of the current thread. If the ThreadGroup and its parent 
ThreadGroups do not override uncaughtException, then the default handler's 
uncaughtException method is invoked. 


In situations where it is desirable to ensure that one block of code is always executed 
after another, even if that other block of code completes abruptly, a try statement with a 
finally clause (§14.20.2) may be used. 


If a try or catch block in a try-finally or try-catch-finally statement completes 
abruptly, then the finally clause is executed during propagation of the exception, even 
if no matching catch clause is ultimately found. 


If a finally clause is executed because of abrupt completion of a try block and the 
finally clause itself completes abruptly, then the reason for the abrupt completion of the 
try block is discarded and the new reason for abrupt completion is propagated from there. 


The exact rules for abrupt completion and for the catching of exceptions are specified 
in detail with the specification of each statement in §14 (Blocks and Statements) and for 
expressions in §15 (Expressions) (especially §15.6). 


Example 11.3-1. Throwing and Catching Exceptions 


The following program declares an exception class TestException. The main method 
of class Test invokes the thrower method four times, causing exceptions to be thrown 
three of the four times. The try statement in method main catches each exception that 
the thrower throws. Whether the invocation of thrower completes normally or abruptly, 
a message is printed describing what happened. 
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class TestException extends Exception { 
TestException () { super(); } 
TestException(String s) { super(s); } 


class Test { 
public static void main(String[] args) { 
for (String arg : args) { 
try { 
thrower (arg); 
System.out.printin("Test \"" + arg + 
"\" didn't throw an exception") ; 
} catch (Exception e) { 
System.out.printin("Test \"" + arg + 
"\" threw a " + e.getClass() + 
"\n with message: " + 
e.getMessage()); 


} 
static int thrower(String s) throws TestException { 
try { 
if (s.equals("divide")) { 
int i = 0; 
return i/i; 


if (s.equals("null")) { 
s = null; 
return s.length(); 


if (s.equals("test")) { 


throw new TestException("Test message") ; 
} 
return 0; 
} finally { 
System.out.printin("[thrower(\"" + s + "\") done]"); 


If we execute the program, passing it the arguments: 
divide null not test 


it produces the output: 
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hrower ("divide") done] 
Test "divide" threw a class java.lang.ArithmeticException 
with message: / by zero 

thrower ("null") done] 

Test "null" threw a class java.lang.NullPointerException 
with message: null 

thrower ("not") done] 

Test "not" didn't throw an exception 
thrower ("test") done] 

Test "test" threw a class TestException 


with message: Test message 


The declaration of the method thrower must have a throws clause because it can throw 
instances of TestException, which is a checked exception class (§11.1.1). A compile- 
time error would occur if the throws clause were omitted. 


Notice that the finally clause is executed on every invocation of thrower, whether or 
not an exception occurs, as shown by the "[thrower(...) done]" output that occurs 
for each invocation. 
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Execution 


Tiss chapter specifies activities that occur during execution of a program. It is 
organized around the life cycle of the Java Virtual Machine and of the classes, 
interfaces, and objects that form a program. 


The Java Virtual Machine starts up by loading a specified class or interface, then 
invoking the method main in this specified class or interface. Section §12.1 outlines 
the loading, linking, and initialization steps involved in executing main, as an 
introduction to the concepts in this chapter. Further sections specify the details of 
loading (§12.2), linking ($12.3), and initialization ($12.4). 


The chapter continues with a specification of the procedures for creation of new 
class instances ($12.5); and finalization of class instances (§12.6). It concludes by 
describing the unloading of classes (§12.7) and the procedure followed when a 
program exits ($12.8). 


12.1 Java Virtual Machine Startup 


The Java Virtual Machine starts execution by invoking the method main of some 
specified class or interface, passing it a single argument which is an array of strings. 
In the examples in this specification, this first class is typically called Test. 


The precise semantics of Java Virtual Machine startup are given in Chapter 5 of 
The Java Virtual Machine Specification, Java SE 12 Edition. Here we present an 
overview of the process from the viewpoint of the Java programming language. 


The manner in which the initial class or interface is specified to the Java Virtual 
Machine is beyond the scope of this specification, but it is typical, in host 
environments that use command lines, for the fully qualified name of the class or 
interface to be specified as a command line argument and for following command 
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line arguments to be used as strings to be provided as the argument to the method 


main. 
For example, in a UNIX implementation, the command line: 
java Test reboot Bob Dot Enzo 


will typically start a Java Virtual Machine by invoking method main of class Test (a class 


in an unnamed package), passing it an array containing the four strings "reboot", "Bob", 
"Dot", and "Enzo". 


We now outline the steps the Java Virtual Machine may take to execute Test, as 
an example of the loading, linking, and initialization processes that are described 
further in later sections. 


12.1.1 Load the Class Test 


The initial attempt to execute the method main of class Test discovers that the class 
Test is not loaded - that is, that the Java Virtual Machine does not currently contain 
a binary representation for this class. The Java Virtual Machine then uses a class 
loader to attempt to find such a binary representation. If this process fails, then an 
error is thrown. This loading process is described further in §12.2. 


12.1.2 Link Test: Verify, Prepare, (Optionally) Resolve 


After Test 1s loaded, it must be initialized before main can be invoked. And Test, 
like all (class or interface) types, must be linked before it is initialized. Linking 
involves verification, preparation, and (optionally) resolution. Linking is described 
further in §12.3. 


Verification checks that the loaded representation of Test is well-formed, with a 
proper symbol table. Verification also checks that the code that implements Test 
obeys the semantic requirements of the Java programming language and the Java 
Virtual Machine. If a problem is detected during verification, then an error is 
thrown. Verification is described further in §12.3.1. 


Preparation involves allocation of static storage and any data structures that are 
used internally by the implementation of the Java Virtual Machine, such as method 
tables. Preparation is described further in §12.3.2. 


Resolution is the process of checking symbolic references from Test to other 
classes and interfaces, by loading the other classes and interfaces that are mentioned 
and checking that the references are correct. 


EXECUTION Java Virtual Machine Startup 


The resolution step is optional at the time of initial linkage. An implementation may 
resolve symbolic references from a class or interface that is being linked very early, 
even to the point of resolving all symbolic references from the classes and interfaces 
that are further referenced, recursively. (This resolution may result in errors from 
these further loading and linking steps.) This implementation choice represents one 
extreme and is similar to the kind of "static" linkage that has been done for many 
years in simple implementations of the C language. (In these implementations, 
a compiled program is typically represented as an "a.out" file that contains a 
fully-linked version of the program, including completely resolved links to library 
routines used by the program. Copies of these library routines are included in the 
"a.out” file.) 


An implementation may instead choose to resolve a symbolic reference only when 
it is actively used; consistent use of this strategy for all symbolic references would 
represent the "laziest" form of resolution. In this case, if Test had several symbolic 
references to another class, then the references might be resolved one at a time, 
as they are used, or perhaps not at all, if these references were never used during 
execution of the program. 


The only requirement on when resolution is performed is that any errors detected 
during resolution must be thrown at a point in the program where some action 
is taken by the program that might, directly or indirectly, require linkage to the 
class or interface involved in the error. Using the "static" example implementation 
choice described above, loading and linkage errors could occur before the program 
is executed if they involved a class or interface mentioned in the class Test or 
any of the further, recursively referenced, classes and interfaces. In a system that 
implemented the "laziest" resolution, these errors would be thrown only when an 
incorrect symbolic reference is actively used. 


The resolution process is described further in §12.3.3. 


12.1.3 Initialize Test: Execute Initializers 


In our continuing example, the Java Virtual Machine is still trying to execute the 
method main of class Test. This is permitted only if the class has been initialized 
($12.4.1). 


Initialization consists of execution of any class variable initializers and static 
initializers of the class Test, in textual order. But before Test can be initialized, 
its direct superclass must be initialized, as well as the direct superclass of its direct 
superclass, and so on, recursively. In the simplest case, Test has object as its 
implicit direct superclass; if class Object has not yet been initialized, then it must 
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be initialized before Test is initialized. Class Object has no superclass, so the 
recursion terminates here. 


If class Test has another class super as its superclass, then super must be 
initialized before Test. This requires loading, verifying, and preparing super if 
this has not already been done and, depending on the implementation, may also 
involve resolving the symbolic references from Super and so on, recursively. 


Initialization may thus cause loading, linking, and initialization errors, including 
such errors involving other types. 


The initialization process is described further in $12.4. 


12.1.4 Invoke test .main 


Finally, after completion of the initialization for class Test (during which other 
consequential loading, linking, and initializing may have occurred), the method 
main Of Test is invoked. 


The method main must be declared public, static, and void. It must specify a 
formal parameter (§8.4.1) whose declared type is array of st ring. Therefore, either 
of the following declarations is acceptable: 


public static void main(String[] args) 


public static void main(String... args) 


12.2 Loading of Classes and Interfaces 


Loading refers to the process of finding the binary form of a class or interface type 
with a particular name, perhaps by computing it on the fly, but more typically by 
retrieving a binary representation previously computed from source code by a Java 
compiler, and constructing, from that binary form, a Class object to represent the 
class or interface. 


The precise semantics of loading are given in Chapter 5 of The Java Virtual 
Machine Specification, Java SE 12 Edition. Here we present an overview of the 
process from the viewpoint of the Java programming language. 


The binary format of a class or interface is normally the class file format described 
in The Java Virtual Machine Specification, Java SE 12 Edition cited above, but 
other formats are possible, provided they meet the requirements specified in $13.1. 
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The method defineClass of class ClassLoader may be used to construct Class 
objects from binary representations in the class file format. 


Well-behaved class loaders maintain these properties: 


¢ Given the same name, a good class loader should always return the same class 
object. 


¢ Ifa class loader 11 delegates loading of a class c to another loader 12, then for 
any type r that occurs as the direct superclass or a direct superinterface of c, or 
as the type of a field in c, or as the type of a formal parameter of a method or 
constructor in c, or as a return type of a method in c, £1 and 12 should return 
the same Class object. 


A malicious class loader could violate these properties. However, it could not 
undermine the security of the type system, because the Java Virtual Machine guards 
against this. 


For further discussion of these issues, see The Java Virtual Machine Specification, Java SE 
12 Edition and the paper Dynamic Class Loading in the Java Virtual Machine, by Sheng 
Liang and Gilad Bracha, in Proceedings of OOPSLA '98, published as ACM SIGPLAN 
Notices, Volume 33, Number 10, October 1998, pages 36-44. A basic principle of the design 
of the Java programming language is that the run-time type system cannot be subverted 
by code written in the Java programming language, not even by implementations of such 
otherwise sensitive system classes as ClassLoader and SecurityManager. 


12.2.1 The Loading Process 


The loading process is implemented by the class ClassLoader and its subclasses. 


Different subclasses of ClassLoader may implement different loading policies. In 
particular, a class loader may cache binary representations of classes and interfaces, 
prefetch them based on expected usage, or load a group of related classes together. 
These activities may not be completely transparent to a running application if, for 
example, a newly compiled version of a class is not found because an older version 
is cached by a class loader. It is the responsibility of a class loader, however, to 
reflect loading errors only at points in the program where they could have arisen 
without prefetching or group loading. 


If an error occurs during class loading, then an instance of one of the following 
subclasses of class LinkageError will be thrown at any point in the program that 
(directly or indirectly) uses the type: 


* ClassCircularityError: A class or interface could not be loaded because it 
would be its own superclass or superinterface (§8.1.4, §9.1.3, §13.4.4). 
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* ClassFormatError: The binary data that purports to specify a requested 
compiled class or interface is malformed. 


* NoClassDefFoundError: No definition for a requested class or interface could 
be found by the relevant class loader. 


Because loading involves the allocation of new data structures, it may fail with an 


OutOfMemoryError. 


12.3. Linking of Classes and Interfaces 


Linking is the process of taking a binary form of a class or interface type and 
combining it into the run-time state of the Java Virtual Machine, so that it can be 
executed. A class or interface type is always loaded before it is linked. 


Three different activities are involved in linking: verification, preparation, and 
resolution of symbolic references. 


The precise semantics of linking are given in Chapter 5 of The Java Virtual 
Machine Specification, Java SE 12 Edition. Here we present an overview of the 
process from the viewpoint of the Java programming language. 


This specification allows an implementation flexibility as to when linking activities 
(and, because of recursion, loading) take place, provided that the semantics of the 
Java programming language are respected, that a class or interface is completely 
verified and prepared before it is initialized, and that errors detected during linkage 
are thrown at a point in the program where some action is taken by the program 
that might require linkage to the class or interface involved in the error. 


For example, an implementation may choose to resolve each symbolic reference 
in a class or interface individually, only when it is used (lazy or late resolution), or 
to resolve them all at once while the class is being verified (static resolution). This 
means that the resolution process may continue, in some implementations, after a 
class or interface has been initialized. 


Because linking involves the allocation of new data structures, it may fail with an 


OutOfMemoryError. 


12.3.1 Verification of the Binary Representation 


Verification ensures that the binary representation of a class or interface is 
structurally correct. For example, it checks that every instruction has a valid 
operation code; that every branch instruction branches to the start of some other 
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instruction, rather than into the middle of an instruction; that every method is 
provided with a structurally correct signature; and that every instruction obeys the 
type discipline of the Java Virtual Machine language. 


If an error occurs during verification, then an instance of the following subclass 
of class LinkageError will be thrown at the point in the program that caused the 
class to be verified: 


* VerifyError: The binary definition for a class or interface failed to pass a set of 
required checks to verify that it obeys the semantics of the Java Virtual Machine 
language and that it cannot violate the integrity of the Java Virtual Machine. (See 
§13.4.2, §13.4.4, §13.4.9, and §13.4.17 for some examples.) 


12.3.2 Preparation of a Class or Interface Type 


Preparation involves creating the static fields (class variables and constants) for 
a class or interface and initializing such fields to the default values (§4.12.5). This 
does not require the execution of any source code; explicit initializers for static 
fields are executed as part of initialization ($12.4), not preparation. 


Implementations of the Java Virtual Machine may precompute additional data structures 
at preparation time in order to make later operations on a class or interface more efficient. 
One particularly useful data structure is a "method table" or other data structure that allows 
any method to be invoked on instances of a class without requiring a search of superclasses 
at invocation time. 


12.3.3. Resolution of Symbolic References 


The binary representation of a class or interface references other classes and 
interfaces and their fields, methods, and constructors symbolically, using the binary 
names (§13.1) of the other classes and interfaces (§13.1). For fields and methods, 
these symbolic references include the name of the class or interface type of which 
the field or method is a member, as well as the name of the field or method itself, 
together with appropriate type information. 


Before a symbolic reference can be used it must undergo resolution, wherein a 
symbolic reference is checked to be correct and, typically, replaced with a direct 
reference that can be more efficiently processed if the reference is used repeatedly. 


If an error occurs during resolution, then an error will be thrown. Most 
typically, this will be an instance of one of the following subclasses of the class 
IncompatibleClassChangeError, but it may also be an instance of some other 
subclass of IncompatibleClassChangeError or even an instance of the class 
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Incompat ibleClassChangeError itself. This error may be thrown at any point in 


the program that uses a symbolic reference to the type, directly or indirectly: 


* IllegalAccessError: A symbolic reference has been encountered that specifies 
a use or assignment of a field, or invocation of a method, or creation of an 
instance of a class, to which the code containing the reference does not have 
access because the field or method was declared with private, protected, or 
package access (not public), or because the class was not declared public ina 
package that is exported or opened to the code containing the reference. 


This can occur, for example, if a field that is originally declared public is changed to 
be private after another class that refers to the field has been compiled (§13.4.7); or 
if the package in which a public class is declared ceases to be exported by its module 
after another module that refers to the class has been compiled (§ 13.3). 


* InstantiationError: A symbolic reference has been encountered that is used 
in class instance creation expression, but an instance cannot be created because 
the reference turns out to refer to an interface or to an abstract class. 


This can occur, for example, if a class that is originally not abstract is changed to 
be abstract after another class that refers to the class in question has been compiled 
(§13.4.1). 


* NoSuchFieldError: A symbolic reference has been encountered that refers to a 


specific field of a specific class or interface, but the class or interface does not 
contain a field of that name. 


This can occur, for example, if a field declaration was deleted from a class after another 
class that refers to the field was compiled (§ 13.4.8). 


* NoSuchMethodError: A symbolic reference has been encountered that refers to 
a specific method of a specific class or interface, but the class or interface does 
not contain a method of that signature. 


This can occur, for example, if a method declaration was deleted from a class after 
another class that refers to the method was compiled (§13.4.12). 


Additionally, an UnsatisfiedLinkError, a subclass of LinkageError, may be 
thrown if a class declares a native method for which no implementation can be 
found. The error will occur if the method is used, or earlier, depending on what 
kind of resolution strategy is being used by an implementation of the Java Virtual 
Machine (§12.3). 
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12.4 Initialization of Classes and Interfaces 


Initialization of a class consists of executing its static initializers and the initializers 
for static fields (class variables) declared in the class. 


Initialization of an interface consists of executing the initializers for fields 
(constants) declared in the interface. 


12.4.1 When Initialization Occurs 


A class or interface type r will be initialized immediately before the first occurrence 
of any one of the following: 


¢ ris aclass and an instance of rT is created. 
¢ A static method declared by rT is invoked. 
¢ A static field declared by r is assigned. 


¢ A static field declared by r is used and the field is not a constant variable 
($4.12.4). 


When a class is initialized, its superclasses are initialized (if they have not been 
previously initialized), as well as any superinterfaces (§8.1.5) that declare any 
default methods (§9.4.3) (if they have not been previously initialized). Initialization 
of an interface does not, of itself, cause initialization of any of its superinterfaces. 


A reference to a static field (§8.3.1.1) causes initialization of only the class or 
interface that actually declares it, even though it might be referred to through the 
name of a subclass, a subinterface, or a class that implements an interface. 


Invocation of certain reflective methods in class class and in package 
java.lang.reflect also causes class or interface initialization. 


A class or interface will not be initialized under any other circumstance. 


Note that a compiler may generate synthetic default methods in an interface, that is, default 
methods that are neither explicitly nor implicitly declared ($13.1). Such methods will 
trigger the interface's initialization despite the source code giving no indication that the 
interface should be initialized. 


The intent is that a class or interface type has a set of initializers that put it in a 
consistent state, and that this state is the first state that is observed by other classes. 
The static initializers and class variable initializers are executed in textual order, 
and may not refer to class variables declared in the class whose declarations appear 
textually after the use, even though these class variables are in scope (§8.3.3). 
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This restriction is designed to detect, at compile time, most circular or otherwise 
malformed initializations. 


The fact that initialization code is unrestricted allows examples to be constructed 
where the value of a class variable can be observed when it still has its initial default 
value, before its initializing expression is evaluated, but such examples are rare in 
practice. (Such examples can be also constructed for instance variable initialization 
($12.5).) The full power of the Java programming language is available in these 
initializers; programmers must exercise some care. This power places an extra 
burden on code generators, but this burden would arise in any case because the 
Java programming language is concurrent (§12.4.2). 


Example 12.4.1-1. Superclasses Are Initialized Before Subclasses 


class Super { 
static System.out.print ("Super "); } 


lass One { 
static System.out.print ("One "); } 


Q 


lass Two extends Super { 
static System.out.print ("Two "); } 


Q 


lass Test 
public static void main(String[] args) { 
One o = null; 


Q 


Two t = new Two(); 
System.out.printiln((Object)o == (Object)t); 


This program produces the output: 
Super Two false 


The class One is never initialized, because it not used actively and therefore is never linked 
to. The class Two is initialized only after its superclass Super has been initialized. 


Example 12.4.1-2. Only The Class That Declares st at ic Field Is Initialized 


class Super { 
static int taxi = 1729; 
} 
class Sub extends Super { 
static { System.out.print ("Sub "); } 
} 
class Test { 
public static void main(String[] args) { 
System.out.printin(Sub.taxi) ; 
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This program prints only: 
1729 


because the class Sub is never initialized; the reference to Sub.taxi is a reference to a 
field actually declared in class Super and does not trigger initialization of the class Sub. 


Example 12.4.1-3. Interface Initialization Does Not Initialize Superinterfaces 


interface I 

int i= 1, ii = Test.out("ii", 2); 
} 
interface J extends I { 

int j = Test.out("j", 3), 433 = Test.out("jj", 4); 
} 
interface K extends J { 

int k = Test.out("k", 5); 


} 
class Test { 
public static void main(String[] args) { 
System.out.println(J.i); 
System.out.println(K.j); 
} 
static int out(String s, int i) { 
System.out.println(s + "=" + i); 
return i; 


This program produces the output: 


The reference to J.i is toa field that is a constant variable (§4.12.4); therefore, it does not 
cause I to be initialized (§13.4.9). 


The reference to K. 3 is a reference to a field actually declared in interface J that is not a 
constant variable; this causes initialization of the fields of interface J, but not those of its 
superinterface I, nor those of interface K. 


Despite the fact that the name K is used to refer to field 3 of interface J, interface K is not 
initialized. 
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12.4.2 Detailed Initialization Procedure 


Because the Java programming language is multithreaded, initialization of a class 
or interface requires careful synchronization, since some other thread may be trying 
to initialize the same class or interface at the same time. There is also the possibility 
that initialization of a class or interface may be requested recursively as part of the 
initialization of that class or interface; for example, a variable initializer in class a 
might invoke a method of an unrelated class 8B, which might in turn invoke a method 
of class a. The implementation of the Java Virtual Machine is responsible for 
taking care of synchronization and recursive initialization by using the following 
procedure. 


The procedure assumes that the class object has already been verified and 
prepared, and that the class object contains state that indicates one of four 
situations: 


¢ This Class object is verified and prepared but not initialized. 
¢ This Class object is being initialized by some particular thread r. 
¢ This Class object is fully initialized and ready for use. 


¢ This Class object is in an erroneous state, perhaps because initialization was 
attempted and failed. 


For each class or interface c, there is a unique initialization lock tc. The mapping 
from c to tc is left to the discretion of the Java Virtual Machine implementation. 
The procedure for initializing c is then as follows: 


1. Synchronize on the initialization lock, tc, for c. This involves waiting until the 
current thread can acquire Lc. 


2. Ifthe class object for c indicates that initialization is in progress for c by some 
other thread, then release xtc and block the current thread until informed that 
the in-progress initialization has completed, at which time repeat this step. 


3. If the class object for c indicates that initialization is in progress for c by the 
current thread, then this must be a recursive request for initialization. Release 
Lc and complete normally. 


4. Ifthe class object for c indicates that c has already been initialized, then no 
further action is required. Release tc and complete normally. 


5. If the class object for c is in an erroneous state, then initialization is not 
possible. Release Lc and throw a NoClassDefFoundError. 


EXECUTION Initialization of Classes and Interfaces 


10. 


11. 


12. 


Otherwise, record the fact that initialization of the class object for c is in 
progress by the current thread, and release tc. 


Then, initialize the static fields of c which are constant variables (§4.12.4, 
§8.3.2, §9.3.1). 


Next, if cis a class rather than an interface, then let sc be its superclass and 
let SI,, ..., SZ, be all superinterfaces of c that declare at least one default 
method. The order of superinterfaces is given by a recursive enumeration over 
the superinterface hierarchy of each interface directly implemented by c (in 
the left-to-right order of c's implements clause). For each interface z directly 
implemented by c, the enumeration recurs on 1's superinterfaces (in the left- 
to-right order of r's extends clause) before returning 1. 


For each s in the list [ sc, Sz, ..., STn ], if s has not yet been initialized, then 
recursively perform this entire procedure for s. If necessary, verify and prepare 
S first. 


If the initialization of s completes abruptly because of a thrown exception, then 
acquire Lc, label the class object for cas erroneous, notify all waiting threads, 
release Lc, and complete abruptly, throwing the same exception that resulted 
from initializing s. 


Next, determine whether assertions are enabled ($14.10) for c by querying its 
defining class loader. 


Next, execute either the class variable initializers and static initializers of the 
class, or the field initializers of the interface, in textual order, as though they 
were a single block. 


If the execution of the initializers completes normally, then acquire xc, label 
the class object for cas fully initialized, notify all waiting threads, release Lc, 
and complete this procedure normally. 


Otherwise, the initializers must have completed abruptly by throwing some 
exception E. If the class of £ is not Error or one of its subclasses, then create 
a new instance of the class ExceptionInInitializerError, With E as the 
argument, and use this object in place of z in the following step. If a new 
instance of ExceptionInInitializerError cannot be created because an 
OutOfMemoryError occurs, then instead use an OutOfMemoryError object in 
place of = in the following step. 


Acquire tc, label the class object for c as erroneous, notify all waiting 
threads, release tc, and complete this procedure abruptly with reason = or its 
replacement as determined in the previous step. 
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An implementation may optimize this procedure by eliding the lock acquisition in step 1 
(and release in step 4/5) when it can determine that the initialization of the class has already 
completed, provided that, in terms of the memory model, all happens-before orderings that 
would exist if the lock were acquired, still exist when the optimization is performed. 


Code generators need to preserve the points of possible initialization of a class or interface, 
inserting an invocation of the initialization procedure just described. If this initialization 
procedure completes normally and the Class object is fully initialized and ready for use, 
then the invocation of the initialization procedure is no longer necessary and it may be 
eliminated from the code - for example, by patching it out or otherwise regenerating the 
code. 


Compile-time analysis may, in some cases, be able to eliminate many of the checks 
that a type has been initialized from the generated code, if an initialization order for a 
group of related types can be determined. Such analysis must, however, fully account for 
concurrency and for the fact that initialization code is unrestricted. 


12.5 Creation of New Class Instances 


A new class instance is explicitly created when evaluation of a class instance 
creation expression ($15.9) causes a class to be instantiated. 


A new class instance may be implicitly created in the following situations: 


Loading of aclass or interface that contains a string literal ($3.10.5) may create a 
new String object to represent the literal. (This will not occur if a string denoting 
the same sequence of Unicode code points has previously been interned.) 


Execution of an operation that causes boxing conversion (§5.1.7). Boxing 
conversion may create a new object of a wrapper class (Boolean, Byte, Short, 
Character, Integer, Long, Float, Double) associated with one of the primitive 


types. 


Execution of a string concatenation operator + (§15.18.1) that is not part of a 
constant expression (§15.28) always creates a new St ring object to represent the 
result. String concatenation operators may also create temporary wrapper objects 
for a value of a primitive type. 


Evaluation of a method reference expression ($15.13.3) or a lambda expression 
($15.27.4) may require that a new instance of a class that implements a functional 
interface type be created. 


Each of these situations identifies a particular constructor (§8.8) to be called with 
specified arguments (possibly none) as part of the class instance creation process. 
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Whenever a new class instance is created, memory space is allocated for it with 
room for all the instance variables declared in the class type and all the instance 
variables declared in each superclass of the class type, including all the instance 
variables that may be hidden (§8.3). 


If there is not sufficient space available to allocate memory for the object, then 
creation of the class instance completes abruptly with an outOfMemoryError. 
Otherwise, all the instance variables in the new object, including those declared in 
superclasses, are initialized to their default values (§4.12.5). 


Just before a reference to the newly created object is returned as the result, the 
indicated constructor is processed to initialize the new object using the following 
procedure: 


1. Assign the arguments for the constructor to newly created parameter variables 
for this constructor invocation. 


2. If this constructor begins with an explicit constructor invocation (§$8.8.7.1) of 
another constructor in the same class (using this), then evaluate the arguments 
and process that constructor invocation recursively using these same five 
steps. If that constructor invocation completes abruptly, then this procedure 
completes abruptly for the same reason; otherwise, continue with step 5. 


3. This constructor does not begin with an explicit constructor invocation of 
another constructor in the same class (using this). If this constructor is for 
a class other than object, then this constructor will begin with an explicit 
or implicit invocation of a superclass constructor (using super). Evaluate the 
arguments and process that superclass constructor invocation recursively using 
these same five steps. If that constructor invocation completes abruptly, then 
this procedure completes abruptly for the same reason. Otherwise, continue 
with step 4. 


4. Execute the instance initializers and instance variable initializers for this class, 
assigning the values of instance variable initializers to the corresponding 
instance variables, in the left-to-right order in which they appear textually in 
the source code for the class. If execution of any of these initializers results 
in an exception, then no further initializers are processed and this procedure 
completes abruptly with that same exception. Otherwise, continue with step 5. 


5. Execute the rest of the body of this constructor. If that execution completes 
abruptly, then this procedure completes abruptly for the same reason. 
Otherwise, this procedure completes normally. 


Unlike C++, the Java programming language does not specify altered rules for 
method dispatch during the creation of a new class instance. If methods are 
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invoked that are overridden in subclasses in the object being initialized, then these 
overriding methods are used, even before the new object is completely initialized. 


Example 12.5-1. Evaluation of Instance Creation 


class Point { 
int x, y; 
Point() { x = 1; y = 1; } 
} 
class ColoredPoint extends Point { 
int color = OxFFOOFF; 
} 
class Test { 
public static void main(String[] args) { 
ColoredPoint cp = new ColoredPoint (); 
System.out.println(cp.color) ; 


Here, a new instance of ColoredPoint is created. First, space is allocated for the new 
ColoredPoint, to hold the fields x, y, and color. All these fields are then initialized to 
their default values (in this case, 0 for each field). Next, the ColoredPoint constructor 
with no arguments is first invoked. Since ColoredPoint declares no constructors, a default 
constructor of the following form is implicitly declared: 


ColoredPoint() { super(); } 


This constructor then invokes the Point constructor with no arguments. The Point 
constructor does not begin with an invocation of a constructor, so the Java compiler 
provides an implicit invocation of its superclass constructor of no arguments, as though it 
had been written: 


Point() { super(); x = 1; y= 1; } 
Therefore, the constructor for Object which takes no arguments is invoked. 


The class Object has no superclass, so the recursion terminates here. Next, any instance 
initializers and instance variable initializers of Object are invoked. Next, the body of the 
constructor of Object that takes no arguments is executed. No such constructor is declared 
in Object, so the Java compiler supplies a default one, which in this special case is: 


Object() { } 
This constructor executes without effect and returns. 


Next, all initializers for the instance variables of class Point are executed. As it happens, 
the declarations of x and y do not provide any initialization expressions, so no action is 
required for this step of the example. Then the body of the Point constructor is executed, 
setting x tol andy tol. 
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Next, the initializers for the instance variables of class ColoredPoint are executed. 
This step assigns the value 0xFFOOFF to color. Finally, the rest of the body of the 
ColoredPoint constructor is executed (the part after the invocation of super); there 
happen to be no statements in the rest of the body, so no further action is required and 
initialization is complete. 


Example 12.5-2. Dynamic Dispatch During Instance Creation 


class Super { 

Super() { printThree(); } 

void printThree() { System.out.println("three"); } 
} 
class Test extends Super { 

int three = (int)Math.PI; // That is, 3 

void printThree() { System.out.printin(three); } 


public static void main(String[] args) { 
Test t = new Test (); 
t.printThree(); 


This program produces the output: 


This shows that the invocation of printThree in the constructor for class Super does 
not invoke the definition of print Three in class Super, but rather invokes the overriding 
definition of printThree in class Test. This method therefore runs before the field 
initializers of Test have been executed, which is why the first value output is 0, the default 
value to which the field three of Test is initialized. The later invocation of printThree 
in method main invokes the same definition of print Three, but by that point the initializer 
for instance variable three has been executed, and so the value 3 is printed. 


12.6 Finalization of Class Instances 


The class object has a protected method called finalize; this method can be 
overridden by other classes. The particular definition of finalize that can be 
invoked for an object is called the finalizer of that object. Before the storage for an 
object is reclaimed by the garbage collector, the Java Virtual Machine will invoke 
the finalizer of that object. 


Finalizers provide a chance to free up resources that cannot be freed automatically 
by an automatic storage manager. In such situations, simply reclaiming the memory 
used by an object would not guarantee that the resources it held would be reclaimed. 
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The Java programming language does not specify how soon a finalizer will be 
invoked, except to say that it will happen before the storage for the object is reused. 


The Java programming language does not specify which thread will invoke the 
finalizer for any given object. 


It is important to note that many finalizer threads may be active (this is sometimes needed on 
large shared memory multiprocessors), and that if a large connected data structure becomes 
garbage, all of the finalize methods for every object in that data structure could be 
invoked at the same time, each finalizer invocation running in a different thread. 


The Java programming language imposes no ordering on finalize method calls. 
Finalizers may be called in any order, or even concurrently. 


As an example, if a circularly linked group of unfinalized objects becomes unreachable 
(or finalizer-reachable), then all the objects may become finalizable together. Eventually, 
the finalizers for these objects may be invoked, in any order, or even concurrently 
using multiple threads. If the automatic storage manager later finds that the objects are 
unreachable, then their storage can be reclaimed. 


It is straightforward to implementa class that will cause a set of finalizer-like methods to be 
invoked in a specified order for a set of objects when all the objects become unreachable. 
Defining such a class is left as an exercise for the reader. 


It is guaranteed that the thread that invokes the finalizer will not be holding any 
user-visible synchronization locks when the finalizer is invoked. 


If an uncaught exception is thrown during the finalization, the exception is ignored 
and finalization of that object terminates. 


The completion of an object's constructor happens-before (§17.4.5) the execution 
of its finalize method (in the formal sense of happens-before). 


The finalize method declared in class object takes no action. The fact that class 
Object declares a finalize method means that the finalize method for any class 
can always invoke the finalize method for its superclass. This should always 
be done, unless it is the programmer's intent to nullify the actions of the finalizer 
in the superclass. (Unlike constructors, finalizers do not automatically invoke the 
finalizer for the superclass; such an invocation must be coded explicitly.) 


For efficiency, an implementation may keep track of classes that do not override the 
finalize method of class Object, or override it in a trivial way. 


For example: 


protected void finalize() throws Throwable { 
super.finalize(); 


} 
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We encourage implementations to treat such objects as having a finalizer that is not 
overridden, and to finalize them more efficiently, as described in §12.6.1. 


A finalizer may be invoked explicitly, just like any other method. 


The package java.lang.ref describes weak references, which interact with 
garbage collection and finalization. As with any API that has special interactions 
with the Java programming language, implementors must be cognizant of any 
requirements imposed by the java.lang.ref API. This specification does not 
discuss weak references in any way. Readers are referred to the API documentation 
for details. 


12.6.1 Implementing Finalization 


Every object can be characterized by two attributes: it may be reachable, finalizer- 
reachable, or unreachable, and it may also be unfinalized, finalizable, or finalized. 


A reachable object is any object that can be accessed in any potential continuing 
computation from any live thread. 


A finalizer-reachable object can be reached from some finalizable object through 
some chain of references, but not from any live thread. 


An unreachable object cannot be reached by either means. 
An unfinalized object has never had its finalizer automatically invoked. 
A finalized object has had its finalizer automatically invoked. 


A finalizable object has never had its finalizer automatically invoked, but the Java 
Virtual Machine may eventually automatically invoke its finalizer. 


An object o is not finalizable until its constructor has invoked the constructor 
for Object on o and that invocation has completed successfully (that is, without 
throwing an exception). Every pre-finalization write to a field of an object must be 
visible to the finalization of that object. Furthermore, none of the pre-finalization 
reads of fields of that object may see writes that occur after finalization of that 
object is initiated. 


Optimizing transformations of a program can be designed that reduce the number of 
objects that are reachable to be less than those which would naively be considered 
reachable. For example, a Java compiler or code generator may choose to set a 
variable or parameter that will no longer be used to nu11 to cause the storage for 
such an object to be potentially reclaimable sooner. 
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Another example of this occurs if the values in an object's fields are stored in 
registers. The program may then access the registers instead of the object, and never 
access the object again. This would imply that the object is garbage. Note that this 
sort of optimization is only allowed if references are on the stack, not stored in 
the heap. 


For example, consider the Finalizer Guardian pattern: 


class Foo { 
private final Object finalizerGuardian = new Object() { 
protected void finalize() throws Throwable { 
/* finalize outer Foo object */ 


} 


The finalizer guardian forces super.finalize to be called if a subclass overrides 
finalize and does not explicitly call super. finalize. 


If these optimizations are allowed for references that are stored on the heap, then a Java 
compiler can detect that the finalizerGuardian field is never read, null it out, collect 
the object immediately, and call the finalizer early. This runs counter to the intent: the 
programmer probably wanted to call the Foo finalizer when the Foo instance became 
unreachable. This sort of transformation is therefore not legal: the inner class object should 
be reachable for as long as the outer class object is reachable. 


Transformations of this sort may result in invocations of the finalize method occurring 
earlier than might be otherwise expected. In order to allow the user to prevent this, we 
enforce the notion that synchronization may keep the object alive. If an object's finalizer 
can result in synchronization on that object, then that object must be alive and considered 
reachable whenever a lock is held on it. 


Note that this does not prevent synchronization elimination: synchronization only keeps 
an object alive if a finalizer might synchronize on it. Since the finalizer occurs in another 
thread, in many cases the synchronization could not be removed anyway. 


12.6.2 Interaction with the Memory Model 


It must be possible for the memory model ($17.4) to decide when it can commit 
actions that take place in a finalizer. This section describes the interaction of 
finalization with the memory model. 


Each execution has a number of reachability decision points, labeled di. Each 
action either comes-before di or comes-after di. Other than as explicitly mentioned, 
the comes-before ordering described in this section is unrelated to all other 
orderings in the memory model. 


If ris aread that sees a write w and r comes-before di, then w must come-before di. 
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If x and y are synchronization actions on the same variable or monitor such that 
so(x, y) ($17.4.4) and y comes-before di, then x must come-before di. 


At each reachability decision point, some set of objects are marked as unreachable, 
and some subset of those objects are marked as finalizable. These reachability 
decision points are also the points at which references are checked, enqueued, and 
cleared according to the rules provided in the API documentation for the package 


java.lang.ref. 


The only objects that are considered definitely reachable at a point di are those that 
can be shown to be reachable by the application of these rules: 


¢ An object Bis definitely reachable at di from static fields if there exists a write 
wi toa static field v of aclass c such that the value written by w/ is a reference 
to B, the class cis loaded by a reachable classloader, and there does not exist a 
write w2 to vsuch that hb(w2, w/) is not true and both w/ and w2 come-before di. 


¢ An object Bis definitely reachable from a at di if there is a write w/ to an element 
v of a such that the value written by w/ is a reference to B and there does not 
exist a write w2 to v such that hb(w2, w/) is not true and both w/ and w2 come- 
before di. 


¢ If an object cis definitely reachable from an object B, and object B is definitely 
reachable from an object a, then cis definitely reachable from a. 


If an object x is marked as unreachable at di, then: 
¢ x must not be definitely reachable at di from static fields; and 


e All active uses of x in thread ¢ that come-after di must occur in the finalizer 
invocation for x or as a result of thread t performing a read that comes-after di 
of a reference to x; and 


e All reads that come-after di that see a reference to x must see writes to elements 
of objects that were unreachable at di, or see writes that came-after di. 


An action a is an active use of x if and only if at least one of the following is true: 
* areads or writes an element of x 


¢ a locks or unlocks x and there is a lock action on x that happens-after the 
invocation of the finalizer for x 


* a writes a reference to x 
* ais an active use of an object y, and x is definitely reachable from y 


If an object x is marked as finalizable at di, then: 
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¢ x must be marked as unreachable at di; and 
¢ di must be the only place where x is marked as finalizable; and 


* actions that happen-after the finalizer invocation must come-after di. 


12.7 Unloading of Classes and Interfaces 


An implementation of the Java programming language may unload classes. 


A class or interface may be unloaded if and only if its defining class loader may be 
reclaimed by the garbage collector as discussed in $12.6. 


Classes and interfaces loaded by the bootstrap loader may not be unloaded. 


Class unloading is an optimization that helps reduce memory use. Obviously, the semantics 
of a program should not depend on whether and how a system chooses to implement an 
optimization such as class unloading. To do otherwise would compromise the portability 
of programs. Consequently, whether a class or interface has been unloaded or not should 
be transparent to a program. 


However, if a class or interface c was unloaded while its defining loader was potentially 
reachable, then c might be reloaded. One could never ensure that this would not happen. 
Even if the class was not referenced by any other currently loaded class, it might be 
referenced by some class or interface, D, that had not yet been loaded. When D is loaded by 
Cs defining loader, its execution might cause reloading of c. 


Reloading may not be transparent if, for example, the class has static variables (whose 
state would be lost), static initializers (which may have side effects), or nat ive methods 
(which may retain static state). Furthermore, the hash value of the Class object is 
dependent on its identity. Therefore it is, in general, impossible to reload a class or interface 
in a completely transparent manner. 


Since we can never guarantee that unloading a class or interface whose loader is potentially 
reachable will not cause reloading, and reloading is never transparent, but unloading must 
be transparent, it follows that one must not unload a class or interface while its loader is 
potentially reachable. A similar line of reasoning can be used to deduce that classes and 
interfaces loaded by the bootstrap loader can never be unloaded. 


One must also argue why it is safe to unload a class c if its defining class loader can 
be reclaimed. If the defining loader can be reclaimed, then there can never be any live 
references to it (this includes references that are not live, but might be resurrected by 
finalizers). This, in turn, can only be true if there are can never be any live references to any 
of the classes defined by that loader, including c, either from their instances or from code. 


Class unloading is an optimization that is only significant for applications that load large 
numbers of classes and that stop using most of those classes after some time. A prime 
example of such an application is a web browser, but there are others. A characteristic of 
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such applications is that they manage classes through explicit use of class loaders. As a 
result, the policy outlined above works well for them. 


Strictly speaking, it is not essential that the issue of class unloading be discussed by this 


specification, as class unloading is merely an optimization. However, the issue is very 
subtle, and so it is mentioned here by way of clarification. 


12.8 Program Exit 


A program terminates all its activity and exits when one of two things happens: 
¢ All the threads that are not daemon threads terminate. 


¢ Some thread invokes the exit method of class Runtime or class System, and the 
exit operation is not forbidden by the security manager. 
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Binary Compatibility 


Devetopment tools for the Java programming language should support 
automatic recompilation as necessary whenever source code is available. Particular 
implementations may also store the source and binary of types in a versioning 
database and implement a ClassLoader that uses integrity mechanisms of the 
database to prevent linkage errors by providing binary-compatible versions of types 
to clients. 


Developers of packages and classes that are to be widely distributed face a 
different set of problems. In the Internet, which is our favorite example of a widely 
distributed system, it is often impractical or impossible to automatically recompile 
the pre-existing binaries that directly or indirectly depend on a type that is to be 
changed. Instead, this specification defines a set of changes that developers are 
permitted to make to a package or to a class or interface type while preserving (not 
breaking) compatibility with pre-existing binaries. 


Within the framework of Release-to-Release Binary Compatibility in SOM 
(Forman, Conner, Danforth, and Raper, Proceedings of OOPSLA '95), Java 
programming language binaries are binary compatible under all relevant 
transformations that the authors identify (with some caveats with respect to the 
addition of instance variables). Using their scheme, here is a list of some important 
binary compatible changes that the Java programming language supports: 


¢ Reimplementing existing methods, constructors, and initializers to improve 
performance. 


¢ Changing methods or constructors to return values on inputs for which they 
previously either threw exceptions that normally should not occur or failed by 
going into an infinite loop or causing a deadlock. 


e Adding new fields, methods, or constructors to an existing class or interface. 


¢ Deleting private fields, methods, or constructors of a class. 
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¢ When an entire package is updated, deleting package access fields, methods, or 
constructors of classes and interfaces in the package. 


¢ Reordering the fields, methods, or constructors in an existing type declaration. 
¢ Moving a method upward in the class hierarchy. 

¢ Reordering the list of direct superinterfaces of a class or interface. 

¢ Inserting new class or interface types in the type hierarchy. 


This chapter specifies minimum standards for binary compatibility guaranteed by 
all implementations. The Java programming language guarantees compatibility 
when binaries of classes and interfaces are mixed that are not known to be from 
compatible sources, but whose sources have been modified in the compatible ways 
described here. Note that we are discussing compatibility between releases of an 
application. A discussion of compatibility among releases of the Java SE Platform 
is beyond the scope of this chapter. 


We encourage development systems to provide facilities that alert developers to 
the impact of changes on pre-existing binaries that cannot be recompiled. 


This chapter first specifies some properties that any binary format for the Java 
programming language must have (§13.1). It next defines binary compatibility, 
explaining what it is and what it is not ($13.2). It finally enumerates a large set 
of possible changes to packages (§13.3), classes ($13.4), and interfaces (§13.5), 
specifying which of these changes are guaranteed to preserve binary compatibility 
and which are not. 


Occasionally, references of the form: (JVMS §x.y) are used to indicate concepts 
from The Java Virtual Machine Specification, Java SE 12 Edition. 


13.1 The Form of a Binary 


Programs must be compiled either into the class file format specified by The Java 
Virtual Machine Specification, Java SE 12 Edition, or into a representation that 
can be mapped into that format by a class loader written in the Java programming 
language. 


A class file corresponding to a class or interface declaration must have certain 
properties. A number of these properties are specifically chosen to support source 
code transformations that preserve binary compatibility. The required properties 
are: 
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1. The class or interface must be named by its binary name, which must meet the 
following constraints: 


¢ The binary name of a top level type ($7.6) is its canonical name (86.7). 


¢ The binary name of a member type (§8.5, §9.5) consists of the binary name 
of its immediately enclosing type, followed by $, followed by the simple 
name of the member. 


¢ The binary name of a local class ($14.3) consists of the binary name of 
its immediately enclosing type, followed by $s, followed by a non-empty 
sequence of digits, followed by the simple name of the local class. 


¢ The binary name of an anonymous class (§15.9.5) consists of the binary 
name of its immediately enclosing type, followed by $s, followed by a non- 
empty sequence of digits. 


¢ The binary name of a type variable declared by a generic class or interface 
($8.1.2, §9.1.2) is the binary name of its immediately enclosing type, 
followed by s, followed by the simple name of the type variable. 


¢ The binary name of a type variable declared by a generic method (§8.4.4) is 
the binary name of the type declaring the method, followed by s, followed 
by the descriptor of the method (JVMS §4.3.3), followed by $, followed by 
the simple name of the type variable. 


¢ The binary name of a type variable declared by a generic constructor (§8.8.4) 
is the binary name of the type declaring the constructor, followed by s, 
followed by the descriptor of the constructor (JVMS 84.3.3), followed by s, 
followed by the simple name of the type variable. 


2. A reference to another class or interface type must be symbolic, using the 
binary name of the type. 


3. A reference to a field that is a constant variable (§4.12.4) must be resolved at 
compile time to the value v denoted by the constant variable's initializer. 


If such a field is static, then no reference to the field should be present in the 
code in a binary file, including the class or interface which declared the field. 
Such a field must always appear to have been initialized (§12.4.2); the default 
initial value for the field (if different than v) must never be observed. 


If such a field is non-static, then no reference to the field should be present 
in the code in a binary file, except in the class containing the field. (It will 
be a class rather than an interface, since an interface has only static fields.) 
The class should have code to set the field's value to v during instance creation 
($12.5). 
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Given a legal expression denoting a field access in a class c, referencing a 
field named fF that is not a constant variable and is declared in a (possibly 
distinct) class or interface p, we define the qualifying type of the field reference 
as follows: 


¢ If the expression is referenced by a simple name, then if is a member of the 
current class or interface, c, then let rT be c. Otherwise, let T be the innermost 
lexically enclosing type declaration of which f is a member. In either case, 
T is the qualifying type of the reference. 


e If the reference is of the form TypeName. +f, where TypeName denotes a 
class or interface, then the class or interface denoted by TypeName is the 
qualifying type of the reference. 


¢ If the expression is of the form ExpressionName. £ or Primary. f, then: 


— If the compile-time type of ExpressionName or Primary is an intersection 
type Vv; & ... & Vn (84.9), then the qualifying type of the reference is v. 


— Otherwise, the compile-time type of ExpressionName or Primary is the 
qualifying type of the reference. 


e If the expression is of the form super. f, then the superclass of c is the 
qualifying type of the reference. 


¢ If the expression is of the form TypeName. super. f, then the superclass of 
the class denoted by TypeName is the qualifying type of the reference. 


The reference to f must be compiled into a symbolic reference to the erasure 
($4.6) of the qualifying type of the reference, plus the simple name of the 
field, . The reference must also include a symbolic reference to the erasure 
of the declared type of the field so that the verifier can check that the type is 
as expected. 


Given a method invocation expression or a method reference expression in 
a class or interface c, referencing a method named m declared (or implicitly 
declared (§9.2)) in a (possibly distinct) class or interface p, we define the 
qualifying type of the method invocation as follows: 


¢ If Dis object then the qualifying type of the expression is Object. 
¢ Otherwise: 


— If the method is referenced by a simple name, then if mis a member of the 
current class or interface c, let r be c; otherwise, let T be the innermost 
lexically enclosing type declaration of which mis a member. In either case, 
T is the qualifying type of the method invocation. 
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— If the expression is of the form TypeName .m or ReferenceType: : m, then 
the type denoted by TypeName or ReferenceType is the qualifying type of 
the method invocation. 


— If the expression is of the form ExpressionName.m or Primary.m or 
ExpressionName: :mor Primary : : m, then: 


>» If the compile-time type of ExpressionName or Primary is an 
intersection type v; « ... & V, ($4.9), then the qualifying type of the 
method invocation is v;. 


>» Otherwise, the compile-time type of ExpressionName or Primary is the 
qualifying type of the method invocation. 


— If the expression is of the form super.mor super: :m, then the superclass 
of cis the qualifying type of the method invocation. 


—If the expression is of the form TypeName.super.m_ or 
TypeName. super: :m, then if TypeName denotes a class x, the superclass 
of xis the qualifying type of the method invocation; if TypeName denotes 
an interface x, x is the qualifying type of the method invocation. 


A reference to a method must be resolved at compile time to a symbolic 
reference to the erasure (§4.6) of the qualifying type of the invocation, plus the 
erasure of the signature (§8.4.2) of the method. The signature of a method must 
include all of the following as determined by §15.12.3: 


¢ The simple name of the method 
¢ The number of parameters to the method 
¢ A symbolic reference to the type of each parameter 


A reference to a method must also include either a symbolic reference to the 
erasure of the return type of the denoted method or an indication that the 
denoted method is declared void and does not return a value. 


6. Given a class instance creation expression ($15.9) or an explicit constructor 
invocation statement (§8.8.7.1) or a method reference expression of the form 
ClassType :: new (§15.13) ina class or interface c referencing a constructor m 
declared in a (possibly distinct) class or interface p, we define the qualifying 
type of the constructor invocation as follows: 


¢ If the expression is of the form new D(...) or ExpressionName .new D(...) 
or Primary.new D(...) Of D :: new, then the qualifying type of the 
invocation is D. 
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¢ If the expression is of the form new D(...) {...} or ExpressionName .new 
D(...){...} or Primary.new D(...){...}, then the qualifying type of the 
expression is the compile-time type of the expression. 


e If the expression iS of the form super(...) or 
ExpressionName.super(...) or Primary.super(...), then the qualifying 
type of the expression is the direct superclass of c. 


¢ If the expression is of the form this(...), then the qualifying type of the 
expression is C. 


A reference to a constructor must be resolved at compile time to a symbolic 
reference to the erasure (§4.6) of the qualifying type of the invocation, plus 
the signature of the constructor (§8.8.2). The signature of a constructor must 
include both: 


¢ The number of parameters of the constructor 


¢« A symbolic reference to the type of each formal parameter 


A binary representation for a class or interface must also contain all of the 


following: 

1. If it is a class and is not object, then a symbolic reference to the erasure of 
the direct superclass of this class. 

2. A symbolic reference to the erasure of each direct superinterface, if any. 

3. A specification of each field declared in the class or interface, given as the 
simple name of the field and a symbolic reference to the erasure of the type 
of the field. 

4. Ifitisaclass, then the erased signature of each constructor, as described above. 

5. For each method declared in the class or interface (excluding, for an interface, 
its implicitly declared methods (§9.2)), its erased signature and return type, as 
described above. 

6. The code needed to implement the class or interface: 


¢ Foran interface, code for the field initializers and the implementation of each 
method with a block body (§9.4.3). 


¢ For aclass, code for the field initializers, the instance and static initializers, 
the implementation of each method with a block body (§8.4.7), and the 
implementation of each constructor. 
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10. 


11. 


12. 


Every type must contain sufficient information to recover its canonical name 


($6.7). 


Every member type must have sufficient information to recover its source-level 
access modifier. 


Every nested class and nested interface must have a symbolic reference to its 
immediately enclosing type (§8.1.3). 


Every class must contain symbolic references to all of its member types ($8.5), 
and to all local and anonymous classes that appear in its methods, constructors, 
static initializers, instance initializers, and field initializers. 


Every interface must contain symbolic references to all of its member types 
($9.5), and to all local and anonymous classes that appear in its default methods 
and field initializers. 


A construct emitted by a Java compiler must be marked as synthetic if it does 
not correspond to a construct declared explicitly or implicitly in source code, 
unless the emitted construct is a class initialization method (JVMS §2.9). 


A construct emitted by a Java compiler must be marked as mandated if it 
corresponds to a formal parameter declared implicitly in source code (§8.8.1, 
§8.8.9, §8.9.3, §15.9.5.1). 


The following formal parameters are declared implicitly in source code: 
¢ The first formal parameter of a constructor of a non-private inner member class 
(§8.8.1, §8.8.9). 


¢ The first formal parameter of an anonymous constructor of an anonymous class whose 
superclass is inner or local (not in a static context) (§15.9.5.1). 


¢ The formal parameter name of the valueOf method which is implicitly declared in an 


enum type (§8.9.3). 


For reference, the following constructs are declared implicitly in source code, but are not 
marked as mandated because only formal parameters can be so marked in a class file 
(JVMS §4.7.24): 

¢ Default constructors of classes and enum types (§8.8.9, §8.9.2) 

e Anonymous constructors ($15.9.5.1) 

¢ The values and valueOf methods of enum types (§8.9.3) 

¢ Certain public fields of enum types (§8.9.3) 

¢ Certain public methods of interfaces (§9.2) 


¢ Container annotations (§9.7.5) 
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A class file corresponding to a module declaration must have the properties of 
a class file for a class whose binary name is module-info and which has no 
superclass, no superinterfaces, no fields, and no methods. In addition, the binary 
representation of the module must contain all of the following: 


¢ A specification of the name of the module, given as a symbolic reference to the 
name indicated after module. Also, the specification must include whether the 
module is normal or open (§7.7). 


¢ A specification of each dependence denoted by a requires directive, given as a 
symbolic reference to the name of the module indicated by the directive (§$7.7.1). 
Also, the specification must include whether the dependence is transitive and 
whether the dependence is static. 


¢ A specification of each package denoted by an exports or opens directive, given 
as a symbolic reference to the name of the package indicated by the directive 
($7.7.2). Also, if the directive was qualified, the specification must give symbolic 
references to the names of the modules indicated by the directive's to clause. 


¢ A specification of each service denoted by a uses directive, given as a symbolic 
reference to the name of the type indicated by the directive (§7.7.3). 


¢ A specification of the service providers denoted by a provides directive, given 
as symbolic references to the names of the types indicated by the directive's with 
clause (§7.7.4). Also, the specification must give a symbolic reference to the 
name of the type indicated as the service by the directive. 


The following sections discuss changes that may be made to class and interface type 
declarations without breaking compatibility with pre-existing binaries. Under the 
translation requirements given above, the Java Virtual Machine and its class file 
format support these changes. Any other valid binary format, such as a compressed 
or encrypted representation that is mapped back into class files by a class loader 
under the above requirements, will necessarily support these changes as well. 


13.2 What Binary Compatibility Is and Is Not 


A change to a type is binary compatible with (equivalently, does not break binary 
compatibility with) pre-existing binaries if pre-existing binaries that previously 
linked without error will continue to link without error. 


Binaries are compiled to rely on the accessible members and constructors of other 
classes and interfaces. To preserve binary compatibility, a class or interface should 
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treat its accessible members and constructors, their existence and behavior, as a 
contract with its users. 


The Java programming language is designed to prevent additions to contracts 
and accidental name collisions from breaking binary compatibility. Specifically, 
addition of more methods overloading a particular method name does not break 
compatibility with pre-existing binaries. The method signature that the pre-existing 
binary will use for method lookup is chosen by the overload resolution algorithm 
at compile time (§15.12.2). 


If the Java programming language had been designed so that the particular method to be 
executed was chosen at run time, then such an ambiguity might be detected at run time. Such 
a rule would imply that adding an additional overloaded method so as to make ambiguity 
possible at a call site could break compatibility with an unknown number of pre-existing 
binaries. See §13.4.23 for more discussion. 


Binary compatibility is not the same as source compatibility. In particular, the 
example in §13.4.6 shows that a set of compatible binaries can be produced from 
sources that will not compile all together. This example is typical: a new declaration 
is added, changing the meaning of a name in an unchanged part of the source code, 
while the pre-existing binary for that unchanged part of the source code retains the 
fully-qualified, previous meaning of the name. Producing a consistent set of source 
code requires providing a qualified name or field access expression corresponding 
to the previous meaning. 


13.3 Evolution of Packages and Modules 


A new top level class or interface type may be added to a package without breaking 
compatibility with pre-existing binaries, provided the new type does not reuse a 
name previously given to an unrelated type. If a new type reuses a name previously 
given to an unrelated type, then a conflict may result, since binaries for both types 
could not be loaded by the same class loader. 


Changes in top level class and interface types that are not public and that are nota 
superclass or superinterface, respectively, of a public type, affect only types within 
the package in which they are declared. Such types may be deleted or otherwise 
changed, even if incompatibilities are otherwise described here, provided that the 
affected binaries of that package are updated together. 


If a module that was declared to export or open a package is changed to not export 
or open the package, or to export or open the package to a different set of friends, 
then an IllegalAccessError Is thrown if a pre-existing binary is linked that needs 
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but no longer has access to the public and protected types of the package. Such 
a change is not recommended for modules that have been widely distributed. 


If a module was not declared to export or open a given package, then changing 
the module to export or open the package does not break compatibility with 
pre-existing binaries. However, changing the module to export the package may 
prevent the program from starting, since any module that reads the module may 
also read some other module that exports a package with the same name. 


Adding a requires directive to a module declaration, or adding the transitive 
modifier to a requires directive, does not break compatibility with pre-existing 
binaries. However, it may prevent the program from starting, since the module may 
now read multiple modules that export packages with the same name. 


Deleting a requires directive in a module declaration, or deleting the transitive 
modifier from a requires directive, may break compatibility with any pre-existing 
binary that relied on the directive or modifier for readability of a given module in 
the course of referencing types exported by that module. An IllegalAccessError 
may be thrown when such a reference from a pre-existing binary is linked. 


Adding or deleting a uses or provides directive in a module declaration does not 
break compatibility with pre-existing binaries. 


13.4 Evolution of Classes 


This section describes the effects of changes to the declaration of a class and its 
members and constructors on pre-existing binaries. 


13.4.1 abstract Classes 


If a class that was not declared abstract is changed to be declared abstract, 
then pre-existing binaries that attempt to create new instances of that class will 
throw either an InstantiationError at link time, or (if a reflective method is 
used) an InstantiationException at run time; such a change is therefore not 
recommended for widely distributed classes. 


Changing a class that is declared abst ract to no longer be declared abst ract does 
not break compatibility with pre-existing binaries. 
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13.4.2 final Classes 


If a class that was not declared final is changed to be declared final, then a 
VerifyError is thrown if a binary of a pre-existing subclass of this class is loaded, 
because final classes can have no subclasses; such a change is not recommended 
for widely distributed classes. 


Changing a class that is declared final to no longer be declared final does not 
break compatibility with pre-existing binaries. 


13.4.3 public Classes 


Changing a class that is not declared public to be declared public does not break 
compatibility with pre-existing binaries. 


If a class that was declared public is changed to not be declared public, then an 
IllegalAccessError is thrown if a pre-existing binary is linked that needs but no 
longer has access to the class type; such a change is not recommended for widely 
distributed classes. 


13.4.4 Superclasses and Superinterfaces 


A ClassCircularityError is thrown at load time if a class would be a superclass 
of itself. Changes to the class hierarchy that could result in such a circularity 
when newly compiled binaries are loaded with pre-existing binaries are not 
recommended for widely distributed classes. 


Changing the direct superclass or the set of direct superinterfaces of a class type 
will not break compatibility with pre-existing binaries, provided that the total set of 
superclasses or superinterfaces, respectively, of the class type loses no members. 


If a change to the direct superclass or the set of direct superinterfaces results in any 
class or interface no longer being a superclass or superinterface, respectively, then 
linkage errors may result if pre-existing binaries are loaded with the binary of the 
modified class. Such changes are not recommended for widely distributed classes. 


Example 13.4.4-1. Changing A Superclass 
Suppose that the following test program: 


class Hyper { char h = 'h'; } 
class Super extends Hyper { char s = 's'; } 
class Test extends Super { 
public static void printH(Hyper h) { 
System.out.printin(h.h); 
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} 
public static void main(String[] args) { 
printH(new Super ()); 


is compiled and executed, producing the output: 
h 

Suppose that a new version of class Super is then compiled: 
class Super { char s = 's'; } 


This version of class Super is not a subclass of Hyper. If we then run the existing binaries 
of Hyper and Test with the new version of Super, then a VerifyError is thrown at 
link time. The verifier objects because the result of new Super () cannot be passed as an 
argument in place of a formal parameter of type Hyper, because Super is not a subclass 
of Hyper. 


It is instructive to consider what might happen without the verification step: the program 
might run and print: 


This demonstrates that without the verifier, the Java type system could be defeated by 
linking inconsistent binary files, even though each was produced by a correct Java compiler. 


The lesson is that an implementation that lacks a verifier or fails to use it will not maintain 
type safety and is, therefore, not a valid implementation. 


The requirement that alternatives in a multi-catch clause (§14.20) not be subclasses or 
superclasses of each other is only a source restriction. Assuming the following client code 
is legal: 


try f 
throwAorB () ; 
} catch (ExceptionA | ExceptionB e) { 


where ExceptionaA and Except ionB do not have a subclass/superclass relationship when 
the client is compiled, it is binary compatible with respect to the client for ExceptionA 
and Except ionB to have such a relationship when the client is executed. 


This is analogous to other situations where a class transformation that is binary compatible 
for a client might not be source compatible for the same client. 
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13.4.5 Class Type Parameters 


Adding or removing a type parameter of a class does not, in itself, have any 
implications for binary compatibility. 


If such a type parameter is used in the type of a field or method, that may have the 
normal implications of changing the aforementioned type. 


Renaming a type parameter of a class has no effect with respect to pre-existing 
binaries. 


Changing the first bound of a type parameter of a class may change the erasure 
($4.6) of any member that uses that type parameter in its own type, and this may 
affect binary compatibility. The change of such a bound is analogous to the change 
of the first bound of a type parameter of a method or constructor (§13.4.13). 


Changing any other bound has no effect on binary compatibility. 


13.4.6 Class Body and Member Declarations 


No incompatibility with pre-existing binaries is caused by adding an instance 
(respectively stat ic) member that has the same name and accessibility (for fields), 
or same name and accessibility and signature and return type (for methods), as an 
instance (respectively static) member of a superclass or subclass. No error occurs 
even if the set of classes being linked would encounter a compile-time error. 


Deleting a class member or constructor that is not declared private may cause a 
linkage error if the member or constructor is used by a pre-existing binary. 


Example 13.4.6-1. Changing A Class Body 


class Hyper { 

void hello() { System.out.printlin("hello from Hyper"); } 
} 
class Super extends Hyper { 

void hello() { System.out.printlin("hello from Super"); } 
} 
class Test { 

public static void main(String[] args) { 

new Super().hello(); 

} 

} 


This program produces the output: 
hello from Super 


Suppose that a new version of class Super is produced: 
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class Super extends Hyper {} 


Then, recompiling Super and executing this new binary with the original binaries for Test 
and Hyper produces the output: 


hello from Hyper 


as expected. 


The super keyword can be used to access a method declared in a 
superclass, bypassing any methods declared in the current class. The expression 
super . Identifier is resolved, at compile time, to a method min the superclass s. If 
the method mis an instance method, then the method which is invoked at run time 
is the method with the same signature as m that is a member of the direct superclass 
of the class containing the expression involving super. 


Example 13.4.6-2. Changing A Superclass 


class Hyper { 
void hello() { System.out.printlin("hello from Hyper"); } 
} 
class Super extends Hyper { } 
class Test extends Super { 
public static void main(String[] args) { 
new Test().hello(); 
} 
void hello() { 
super.hello(); 


This program produces the output: 
hello from Hyper 
Suppose that a new version of class Super is produced: 


class Super extends Hyper { 
void hello() { System.out.printlin("hello from Super"); } 


Then, if Super and Hyper are recompiled but not Test, then running the new binaries with 
the existing binary of Test produces the output: 


hello from Super 


as you might expect. 


412 


BINARY COMPATIBILITY Evolution of Classes 


13.4.7 Access to Members and Constructors 


Changing the declared access of a member or constructor to permit less access 
may break compatibility with pre-existing binaries, causing a linkage error to be 
thrown when these binaries are resolved. Less access is permitted if the access 
modifier is changed from package access to private access; from protected 
access to package or private access; or from public access to protected, 
package, or private access. Changing a member or constructor to permit less 
access is therefore not recommended for widely distributed classes. 


Perhaps surprisingly, the binary format is defined so that changing a member or 
constructor to be more accessible does not cause a linkage error when a subclass 
(already) defines a method to have less access. 


Example 13.4.7-1. Changing Accessibility 
If the package points defines the class Point: 


package points; 
public class Point { 
public int x, y; 
protected void print() { 
System.out printin( 4" + 6 405)" Ss ye OTD) 3 
} 


used by the program: 


class Test extends points.Point { 

public static void main(String[] args) { 
Test t = new Test (); 
t.print(); 

} 

protected void print() { 
System.out.printin("Test") ; 

} 


then these classes compile and Test executes to produce the output: 
Test 


If the method print in class Point is changed to be public, and then only the Point 
class is recompiled, and then executed with the previously existing binary for Test, then 
no linkage error occurs. This happens even though it is improper, at compile time, for a 
public method to be overridden by a protected method (as shown by the fact that the 
class Test could not be recompiled using this new Point class unless print in Test were 
changed to be public.) 
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Allowing superclasses to change protected methods to be public without 
breaking binaries of pre-existing subclasses helps make binaries less fragile. 
The alternative, where such a change would cause a linkage error, would create 
additional binary incompatibilities. 


13.4.8 Field Declarations 


Widely distributed programs should not expose any fields to their clients. Apart 
from the binary compatibility issues discussed below, this is generally good 
software engineering practice. Adding a field to a class may break compatibility 
with pre-existing binaries that are not recompiled. 


Assume a reference to a field # with qualifying type r. Assume further that £ is 
in fact an instance (respectively static) field declared in a superclass of 1, s, and 
that the type of fis x. 


If a new field of type x with the same name as f is added to a subclass of s that is a 
superclass of 7 or T itself, then a linkage error may occur. Such a linkage error will 
occur only if, in addition to the above, either one of the following is true: 


¢ The new field is less accessible than the old one. 
¢ The new field is a static (respectively instance) field. 


In particular, no linkage error will occur in the case where a class could no longer 
be recompiled because a field access previously referenced a field of a superclass 
with an incompatible type. The previously compiled class with such a reference 
will continue to reference the field declared in a superclass. 


Example 13.4.8-1. Adding A Field Declaration 


class Hyper { String h = "hyper"; } 
class Super extends Hyper { String s = "Super"; } 
class Test { 
public static void main(String[] args) { 
System.out.println(new Super() -.h); 
} 
} 


This program produces the output: 
hyper 
Suppose a new version of class Super is produced: 


class Super extends Hyper { 
String s = "super"; 
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Then, recompiling Hyper and Super, and executing the resulting new binaries with the old 
binary of Test produces the output: 


hyper 


The field h of Hyper is output by the original binary of Test. While this may seem 
surprising at first, it serves to reduce the number of incompatibilities that occur at run time. 
(In an ideal world, all source files that needed recompilation would be recompiled whenever 
any one of them changed, eliminating such surprises. But such a mass recompilation is 
often impractical or impossible, especially in the Internet. And, as was previously noted, 
such recompilation would sometimes require further changes to the source code.) 


As another example, if the program: 
class Hyper { String h = "Hyper"; } 
class Super extends Hyper { } 
class Test extends Super { 
public static void main(String[] args) { 


String s = new Test().h; 
System.out.printin(s); 


is compiled and executed, it produces the output: 
Hyper 

Suppose that a new version of class Super is then compiled: 
class Super extends Hyper { char h = 'h'; } 


If the resulting binary is used with the existing binaries for Hyper and Test, then the output 
is still: 


Hyper 
even though compiling the source for these binaries: 


class Hyper { String h = "Hyper"; } 
class Super extends Hyper { char h = 'h'; } 
class Test extends Super { 
public static void main(String[] args) { 
String s = new Test().h; 
System.out.printin(s); 
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would result in a compile-time error, because the h in the source code for main would now 
be construed as referring to the char field declared in Super, and a char value can't be 
assigned to a String. 


Deleting a field from a class will break compatibility with any pre-existing binaries 
that reference this field, and a NoSuchFieldError will be thrown when such a 
reference from a pre-existing binary is linked. Only private fields may be safely 
deleted from a widely distributed class. 


For purposes of binary compatibility, adding or removing a field £ whose type 
involves type variables (§4.4) or parameterized types (§4.5) is equivalent to the 
addition (respectively, removal) of a field of the same name whose type is the 
erasure (§4.6) of the type of fF. 


13.4.9 final Fields and static Constant Variables 


If a field that was not declared final is changed to be declared final, then it can 
break compatibility with pre-existing binaries that attempt to assign new values to 
the field. 
Example 13.4.9-1. Changing A Variable To Be final 
class Super { char s; } 
class Test extends Super { 
public static void main(String[] args) { 
Super x = new Super(); 


xpos heal? 
System.out.println(x.s); 


} 


This program produces the output: 


Suppose that a new version of class Super is produced: 
class Super { final char s = 'b'; } 


If Super is recompiled but not Test, then running the new binary with the existing binary 
of Test results ina IllegalAccessError. 


Deleting the keyword final or changing the value to which a field is initialized 
does not break compatibility with existing binaries. 


If a field is a constant variable (§4.12.4), and moreover is static, then deleting 
the keyword final or changing its value will not break compatibility with pre- 
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existing binaries by causing them not to run, but they will not see any new value 
for a usage of the field unless they are recompiled. This result is a side-effect of the 
decision to support conditional compilation ($14.21). (One might suppose that the 
new value is not seen if the usage occurs in a constant expression ($15.28) but is 
seen otherwise. This is not so; pre-existing binaries do not see the new value at all.) 


The best way to avoid problems with "inconstant constants" in widely-distributed 
code is to use static constant variables only for values which truly are unlikely 
ever to change. Other than for true mathematical constants, we recommend that 
source code make very sparing use of static constant variables. 


If the read-only nature of final is required, a better choice is to declare aprivate static 
variable and a suitable accessor method to get its value. Thus we recommend: 


private static int N; 
public static int getN() { return N; } 


rather than: 

public static final int N= ...; 
There is no problem with: 

public static int N= ...; 


if N need not be read-only. 


13.4.10 static Fields 


If a field that is not declared private was not declared static and is changed 
to be declared static, or vice versa, then a linkage error, specifically an 
IncompatibleClassChangeError, will result if the field is used by a pre-existing 
binary which expected a field of the other kind. Such changes are not recommended 
in code that has been widely distributed. 


13.4.11 transient Fields 

Adding or deleting a transient modifier of a field does not break compatibility 
with pre-existing binaries. 

13.4.12 Method and Constructor Declarations 


Adding a method or constructor declaration to a class will not break compatibility 
with any pre-existing binaries, even in the case where a type could no longer be 
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recompiled because an invocation previously referenced a method or constructor 
of a superclass with an incompatible type. The previously compiled class with 
such a reference will continue to reference the method or constructor declared in 
a superclass. 


Assume a reference to a method m with qualifying type 7. Assume further that m is 
in fact an instance (respectively static) method declared in a superclass of Tf, s. 


If a new method of type x with the same signature and return type as mis added to 
a subclass of s that is a superclass of 7 or rT itself, then a linkage error may occur. 
Such a linkage error will occur only if, in addition to the above, either one of the 
following is true: 


¢ The new method is less accessible than the old one. 
¢ The new method is a static (respectively instance) method. 


Deleting a method or constructor from a class may break compatibility 
with any pre-existing binary that referenced this method or constructor; a 
NoSuchMethodError may be thrown when such a reference from a pre-existing 
binary is linked. Such an error will occur only if no method with a matching 
signature and return type is declared in a superclass. 


If the source code for a non-inner class contains no declared constructors, then 
a default constructor with no parameters is implicitly declared (§8.8.9). Adding 
one or more constructor declarations to the source code of such a class will 
prevent this default constructor from being implicitly declared, effectively deleting 
a constructor, unless one of the new constructors also has no parameters, thus 
replacing the default constructor. The default constructor with no parameters is 
given the same access modifier as the class of its declaration, so any replacement 
should have as much or more access if compatibility with pre-existing binaries is 
to be preserved. 


13.4.13 Method and Constructor Type Parameters 


Adding or removing a type parameter of a method or constructor does not, in itself, 
have any implications for binary compatibility. 


If such a type parameter is used in the type of the method or constructor, that may 
have the normal implications of changing the aforementioned type. 


Renaming a type parameter of a method or constructor has no effect with respect 
to pre-existing binaries. 
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Changing the first bound of a type parameter of a method or constructor may change 
the erasure (§4.6) of any member that uses that type parameter in its own type, and 
this may affect binary compatibility. Specifically: 


¢ If the type parameter is used as the type of a field, the effect is as if the field was 
removed and a field with the same name, whose type is the new erasure of the 
type variable, was added. 


If the type parameter is used as the type of any formal parameter of a method, but 
not as the return type, the effect is as if that method were removed, and replaced 
with a new method that is identical except for the types of the aforementioned 
formal parameters, which now have the new erasure of the type parameter as 
their type. 


If the type parameter is used as a return type of a method, but not as the type of 
any formal parameter of the method, the effect is as if that method were removed, 
and replaced with a new method that is identical except for the return type, which 
is now the new erasure of the type parameter. 


If the type parameter is used as a return type of a method and as the type of one 
or more formal parameters of the method, the effect is as if that method were 
removed, and replaced with a new method that is identical except for the return 
type, which is now the new erasure of the type parameter, and except for the 
types of the aforementioned formal parameters, which now have the new erasure 
of the type parameter as their types. 


Changing any other bound has no effect on binary compatibility. 


13.4.14 Method and Constructor Formal Parameters 


Changing the name of a formal parameter of a method or constructor does not 
impact pre-existing binaries. 


Changing the name of a method, or the type of a formal parameter to a method 
or constructor, or adding a parameter to or deleting a parameter from a method or 
constructor declaration creates a method or constructor with a new signature, and 
has the combined effect of deleting the method or constructor with the old signature 
and adding a method or constructor with the new signature (§13.4.12). 


Changing the type of the last formal parameter of a method from T[] to a variable 
arity parameter (§8.4.1) of type r (i.e. to T...), and vice versa, does not impact 
pre-existing binaries. 


For purposes of binary compatibility, adding or removing a method or constructor 
m whose signature involves type variables (§4.4) or parameterized types (§4.5) 
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is equivalent to the addition (respectively, removal) of an otherwise equivalent 
method whose signature is the erasure ($4.6) of the signature of m. 


13.4.15 Method Result Type 


Changing the result type of a method, or replacing a result type with void, or 
replacing void with a result type, has the combined effect of deleting the old 
method and adding a new method with the new result type or newly void result 
(see §13.4.12). 


For purposes of binary compatibility, adding or removing a method or constructor 
m Whose return type involves type variables ($4.4) or parameterized types (§4.5) 
is equivalent to the addition (respectively, removal) of the an otherwise equivalent 
method whose return type is the erasure (§4.6) of the return type of m. 


13.4.16 abstract Methods 


Changing a method that is declared abstract to no longer be declared abstract 
does not break compatibility with pre-existing binaries. 


Changing a method that is not declared abstract to be declared abstract will 
break compatibility with pre-existing binaries that previously invoked the method, 
causing an AbstractMethodError. 


Example 13.4.16-1. Changing A Method To Be abstract 


class Super { void out() { System.out.println("Out"); } } 
class Test extends Super { 
public static void main(String[] args) { 
Test t = new Test(); 
System.out.println("Way "); 
t.out(); 


} 
This program produces the output: 


Way 
Out 


Suppose that a new version of class Super is produced: 


abstract class Super { 
abstract void out(); 


} 
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If Super is recompiled but not Test, then running the new binary with the existing binary 
of Test results in an Abst ractMethodError, because class Test has no implementation 
of the method out, and is therefore is (or should be) abstract. 


13.4.17 final Methods 


Changing a method that is declared final to no longer be declared final does not 
break compatibility with pre-existing binaries. 


Changing an instance method that is not declared final to be declared final may 
break compatibility with existing binaries that depend on the ability to override the 
method. 


Example 13.4.17-1. Changing A Method To Be final 


class Super { void out() { System.out.println("out"); } } 
class Test extends Super { 
public static void main(String[] args) { 


Test t = new Test (); 
t.out(); 

} 

void out() { super.out(); } 


This program produces the output: 
out 
Suppose that a new version of class Super is produced: 
class Super { final void out() { System.out.println("!"); } } 
If Super is recompiled but not Test, then running the new binary with the existing binary 


of Test results ina VerifyError because the class Test improperly tries to override the 
instance method out. 


Changing a class (static) method that is not declared final to be declared final 
does not break compatibility with existing binaries, because the method could not 
have been overridden. 


13.4.18 native Methods 


Adding or deleting a native modifier of a method does not break compatibility 
with pre-existing binaries. 


The impact of changes to types on pre-existing native methods that are not 
recompiled is beyond the scope of this specification and should be provided with 
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the description of an implementation. Implementations are encouraged, but not 
required, to implement native methods in a way that limits such impact. 


13.4.19 static Methods 


If a method that is not declared private is also declared static (that is, a class 
method) and is changed to not be declared st atic (that is, to an instance method), 
or vice versa, then compatibility with pre-existing binaries may be broken, resulting 
in a linkage time error, namely an IncompatibleClassChangeError, if these 
methods are used by the pre-existing binaries. Such changes are not recommended 
in code that has been widely distributed. 


13.4.20 synchronized Methods 


Adding or deleting a synchronized modifier of a method does not break 
compatibility with pre-existing binaries. 


13.4.21 Method and Constructor Throws 


Changes to the throws clause of methods or constructors do not break compatibility 
with pre-existing binaries; these clauses are checked only at compile time. 


13.4.22 Method and Constructor Body 


Changes to the body of a method or constructor do not break compatibility with 
pre-existing binaries. 


The keyword final on a method does not mean that the method can be safely 
inlined; it means only that the method cannot be overridden. It is still possible that a 
new version of that method will be provided at link-time. Furthermore, the structure 
of the original program must be preserved for purposes of reflection. 


Therefore, we note that a Java compiler cannot expand a method inline at compile 
time. In general we suggest that implementations use late-bound (run-time) code 
generation and optimization. 


13.4.23 Method and Constructor Overloading 


Adding new methods or constructors that overload existing methods or constructors 
does not break compatibility with pre-existing binaries. The signature to be used 
for each invocation was determined when these existing binaries were compiled; 
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therefore newly added methods or constructors will not be used, even if their 
signatures are both applicable and more specific than the signature originally 
chosen. 


While adding a new overloaded method or constructor may cause a compile-time 
error the next time a class or interface is compiled because there is no method or 
constructor that is most specific (§15.12.2.5), no such error occurs when a program 
is executed, because no overload resolution is done at execution time. 


Example 13.4.23-1. Adding An Overloaded Method 


class Super { 
static void out(float f) { 
System.out.println("float"); 
} 
} 
class Test { 
public static void main(String[] args) { 
Super.out (2); 
} 


This program produces the output: 
float 
Suppose that a new version of class Super is produced: 


class Super { 
static void out(float f) { System.out.println("float"); } 
static void out(int i) { System.out.println("int"); } 


If Super is recompiled but not Test, then running the new binary with the existing binary 
of Test still produces the output: 


float 
However, if Test is then recompiled, using this new Super, the output is then: 
int 


as might have been naively expected in the previous case. 
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13.4.24 Method Overriding 


If an instance method is added to a subclass and it overrides a method in a 
superclass, then the subclass method will be found by method invocations in pre- 
existing binaries, and these binaries are not impacted. 


If a class method is added to a class, then this method will not be found unless the 
qualifying type of the reference is the subclass type. 


13.4.25 Static Initializers 


Adding, deleting, or changing a static initializer ($8.7) of a class does not impact 
pre-existing binaries. 


13.4.26 Evolution of Enums 


Adding or reordering constants in an enum will not break compatibility with pre- 
existing binaries. 


If a pre-existing binary attempts to access an enum constant that no longer exists, 
the client will fail at run time with a NoSuchFieldError. Therefore such a change 
is not recommended for widely distributed enums. 


In all other respects, the binary compatibility rules for enums are identical to those 
for classes. 


13.5 Evolution of Interfaces 


This section describes the impact of changes to the declaration of an interface and 
its members on pre-existing binaries. 


13.5.1 public Interfaces 


Changing an interface that is not declared public to be declared public does not 
break compatibility with pre-existing binaries. 


If an interface that is declared public is changed to not be declared public, then 
an IllegalAccessError is thrown if a pre-existing binary is linked that needs but 
no longer has access to the interface type, so such a change is not recommended 
for widely distributed interfaces. 
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13.5.2 Superinterfaces 


Changes to the interface hierarchy cause errors in the same way that changes to 
the class hierarchy do, as described in §13.4.4. In particular, changes that result in 
any previous superinterface of a class no longer being a superinterface can break 
compatibility with pre-existing binaries, resulting in a VerifyError. 


13.5.3 Interface Members 


Adding an abstract, private, or static method to an interface does not break 
compatibility with pre-existing binaries. 


Adding a field to a superinterface of c may hide a field inherited from 
a superclass of c. If the original reference was to an instance field, an 
IncompatibleClassChangeError will result. If the original reference was an 
assignment, an IllegalAccessError will result. 


Deleting a member from an interface may cause linkage errors in pre-existing 
binaries. 


Example 13.5.3-1. Deleting An Interface Member 


interface I { void hello(); } 
class Test implements I { 
public static void main(String[] args) { 
I anI = new Test (); 
anI.hello(); 
} 
public void hello() { System.out.printin("hello"); } 
} 


This program produces the output: 
hello 

Suppose that a new version of interface I is compiled: 
interface I {} 


If I is recompiled but not Test, then running the new binary with the existing binary for 
Test will result in a NoSuchMethodError. 


13.5.4 Interface Type Parameters 


The effects of changes to the type parameters of an interface are the same as those 
of analogous changes to the type parameters of a class. 
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13.5.5 Field Declarations 


The considerations for changing field declarations in interfaces are the same as 
those for static final fields in classes, as described in §13.4.8 and §13.4.9. 


13.5.6 Interface Method Declarations 


The considerations for changing method declarations in interfaces include those for 
changing methods in classes, as described in §13.4.7, §13.4.14, §13.4.15, $13.4.19, 
§13.4.21, §13.4.22, and §13.4.23. 


Adding a default method, or changing a method from abstract to default, 
does not break compatibility with pre-existing binaries, but may cause an 
IncompatibleClassChangeError if a pre-existing binary attempts to invoke the 
method. This error occurs if the qualifying type, rT, is a subtype of two interfaces, r 
and J, where both z and 7 declare a default method with the same signature and 
result, and neither z nor 7is a subinterface of the other. 


In other words, adding a default method is a binary-compatible change because it 
does not introduce errors at link time, even if it introduces errors at compile time or 
invocation time. In practice, the risk of accidental clashes occurring by introducing 
a default method are similar to those associated with adding a new method to a 
non-final class. In the event of a clash, adding a method to a class is unlikely to 
trigger a LinkageError, but an accidental override of the method in a child can lead 
to unpredictable method behavior. Both changes can cause errors at compile time. 


Example 13.5.6-1. Adding A Default Method 
interface Painter { 
default void draw() { 
System.out.println("Here's a picture..."); 
} 
} 
interface Cowboy {} 
public class CowboyArtist implements Cowboy, Painter { 
public static void main(String... args) { 
new CowboyArtist () .draw(); 
} 
This program produces the output: 


Here's a picture... 


Suppose that a default method is added to Cowboy: 
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interface Cowboy { 
default void draw() { 
System.out.println("Bang!"); 
} 
} 


If Cowboy is recompiled but not CowboyArtist, then running the new binary 
with the existing binary for CowboyArtist will link without error but cause an 
Incompat ibleClassChangeError when main attempts to invoke draw (). 


13.5.7 Evolution of Annotation Types 


Annotation types behave exactly like any other interface. Adding or removing an 
element from an annotation type is analogous to adding or removing a method. 
There are important considerations governing other changes to annotation types, 
such as making an annotation type repeatable ($9.6.3), but these have no effect on 
the linkage of binaries by the Java Virtual Machine. Rather, such changes affect 
the behavior of reflective APIs that manipulate annotations. The documentation 
of these APIs specifies their behavior when various changes are made to the 
underlying annotation types. 


Adding or removing annotations has no effect on the correct linkage of the binary 
representations of programs in the Java programming language. 
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Blocks and Statements 


THE sequence of execution of a program is controlled by statements, which are 
executed for their effect and do not have values. 


Some statements contain other statements as part of their structure; such other 
statements are substatements of the statement. We say that statement s immediately 
contains statement vu if there is no statement r different from s and vu such that 
sS contains T and Tr contains vu. In the same manner, some statements contain 
expressions (§15 (Expressions)) as part of their structure. 


The first section of this chapter discusses the distinction between normal and 
abrupt completion of statements ($14.1). Most of the remaining sections explain 
the various kinds of statements, describing in detail both their normal behavior and 
any special treatment of abrupt completion. 


Blocks are explained first ($14.2), followed by local class declarations (§14.3) and 
local variable declaration statements ($14.4). 


Next a grammatical maneuver that sidesteps the familiar "dangling else" problem 
($14.5) is explained. 


The last section ($14.21) of this chapter addresses the requirement that every 
statement be reachable in a certain technical sense. 


14.1 Normal and Abrupt Completion of Statements 


Every statement has a normal mode of execution in which certain computational 
steps are carried out. The following sections describe the normal mode of execution 
for each kind of statement. 
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If all the steps are carried out as described, with no indication of abrupt completion, 
the statement is said to complete normally. However, certain events may prevent 
a statement from completing normally: 


¢ The break ($14.15), continue ($14.16), and return ($14.17) statements cause a 
transfer of control that may prevent normal completion of statements that contain 
them. 


¢ Evaluation of certain expressions may throw exceptions from the Java Virtual 
Machine (§15.6). An explicit throw ($14.18) statement also results in an 
exception. An exception causes a transfer of control that may prevent normal 
completion of statements. 


If such an event occurs, then execution of one or more statements may be 
terminated before all steps of their normal mode of execution have completed; such 
statements are said to complete abruptly. 


An abrupt completion always has an associated reason, which is one of the 
following: 


¢ A break with no label 

¢ A break with a given label 

¢ A continue with no label 

¢ A continue with a given label 
¢ A return with no value 

¢ A return with a given value 


e A throw with a given value, including exceptions thrown by the Java Virtual 
Machine 


The terms "complete normally" and "complete abruptly" also apply to the 
evaluation of expressions ($15.6). The only reason an expression can complete 
abruptly is that an exception is thrown, because of either a throw with a given value 
($14.18) or a run-time exception or error (§11 (Exceptions), §15.6). 


If a statement evaluates an expression, abrupt completion of the expression always 
causes the immediate abrupt completion of the statement, with the same reason. 
All succeeding steps in the normal mode of execution are not performed. 


Unless otherwise specified in this chapter, abrupt completion of a substatement 
causes the immediate abrupt completion of the statement itself, with the same 
reason, and all succeeding steps in the normal mode of execution of the statement 
are not performed. 


BLOCKS AND STATEMENTS Blocks 14.2 


Unless otherwise specified, a statement completes normally if all expressions it 
evaluates and all substatements it executes complete normally. 


14.2 Blocks 


A block is a sequence of statements, local class declarations, and local variable 
declaration statements within braces. 


Block: 
{ [BlockStatements] } 


BlockStatements: 
BlockStatement {BlockStatement} 


BlockStatement: 
LocalVariableDeclarationStatement 
ClassDeclaration 
Statement 


A block is executed by executing each of the local variable declaration statements 
and other statements in order from first to last (left to right). If all of these block 
statements complete normally, then the block completes normally. If any of these 
block statements complete abruptly for any reason, then the block completes 
abruptly for the same reason. 


14.3 Local Class Declarations 


A local class is a nested class (§8 (Classes)) that is not a member of any class and 
that has a name (§6.2, §6.7). 


All local classes are inner classes (§8.1.3). 


Every local class declaration statement is immediately contained by a block 
($14.2). Local class declaration statements may be intermixed freely with other 
kinds of statements in the block. 


It is a compile-time error if a local class declaration contains any of the access 
modifiers public, protected, or private (§6.6), or the modifier static (§8.1.1). 


The scope and shadowing of a local class declaration is specified in §6.3 and §6.4. 
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Example 14.3-1. Local Class Declarations 
Here is an example that illustrates several aspects of the rules given above: 


class Global { 
class Cyclic {} 


void foo() { 
new Cyclic(); // create a Global.Cyclic 
class Cyclic extends Cyclic {} // circular definition 


class Local {} 
{ 

class Local {} // compile-time error 
} 
class Local {} // compile-time error 
class AnotherLocal { 

void bar() { 

class Local {} // ok 


} 


class Local {} // ok, not in scope of prior Local 


The first statement of method foo creates an instance of the member class Global.Cyclic 
rather than an instance of the local class Cyclic, because the statement appears prior to 
the scope of the local class declaration. 


The fact that the scope of a local class declaration encompasses its whole declaration (not 
only its body) means that the definition of the local class Cyclic is indeed cyclic because it 
extends itself rather than Global .Cyclic. Consequently, the declaration of the local class 
Cyclic is rejected at compile time. 


Since local class names cannot be redeclared within the same method (or constructor or 
initializer, as the case may be), the second and third declarations of Local result in compile- 
time errors. However, Local can be redeclared in the context of another, more deeply 
nested, class such as AnotherLocal. 


The final declaration of Local is legal, since it occurs outside the scope of any prior 
declaration of Local. 


14.4 Local Variable Declaration Statements 


A local variable declaration statement declares one or more local variable names. 
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LocalVariableDeclarationStatement: 
LocalVariableDeclaration ; 


LocalVariableDeclaration: 
{VariableModifier} LocalVariableType VariableDeclaratorList 


LocalVariableType: 
UnannType 


var 


See §8.3 for UnannType. The following productions from §4.3, §8.3, and §8.4.1 are shown 
here for convenience: 


VariableModifier: 
Annotation 
final 


VariableDeclaratorList: 
VariableDeclarator {, VariableDeclarator} 


VariableDeclarator: 
VariableDeclaratorld [= Variablelnitializer] 


VariableDeclaratorld: 
Identifier [Dims] 


Dims: 
{Annotation} [| ] {{Annotation} [ |} 


VariableInitializer: 
Expression 
Arraylnitializer 


Every local variable declaration statement is immediately contained by a block. 
Local variable declaration statements may be intermixed freely with other kinds of 
statements in the block. 


Apart from local variable declaration statements, a local variable can be declared 
by the header of a basic for statement (§14.14.1), an enhanced for statement 
(§14.14.2), or a try-with-resources statement (§14.20.3). 


The rules for annotation modifiers on a local variable declaration are specified in 
§9.7.4 and §9.7.5. 


It is a compile-time error if final appears more than once as a modifier for a local 
variable declaration. 


It is a compile-time error if the LocalVariableType is var and any of the following 
are true: 
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¢ More than one VariableDeclarator is listed. 


The VariableDeclaratorld has one or more bracket pairs. 


The VariableDeclarator lacks an initializer. 
¢ The initializer of the VariableDeclarator is an Arraylnitializer. 


¢ The initializer of the VariableDeclarator contains a reference to the variable. 


Example 14.4-1. Local Variables Declared With var 


The following code illustrates these rules restricting the use of var: 


vara=1; // Legal 

var b = 2, c = 3.0; // Tllegal: multiple declarators 

var d[] = new int[4]; // Illegal: extra bracket pairs 

var e; // Tllegal: no initializer 

var f = { 6 }; // Tllegal: array initializer 

var g = (g = 7); // Tllegal: self reference in initializer 


These restrictions help to avoid confusion about the type being represented by var. 


14.4.1 Local Variable Declarators and Types 


Each declarator in a local variable declaration declares one local variable, whose 
name is the /dentifier that appears in the declarator. 


If the optional keyword final appears at the start of the declaration, the variable 
being declared is a final variable (§4.12.4). 


The declared type of a local variable is determined as follows: 


¢ If LocalVariableType is an UnannType, and no bracket pairs appear in 
UnannType or VariableDeclaratorId, then UnannType denotes the type of the 
local variable. 


¢ If LocalVariableType is an UnannType, and bracket pairs appear in UnannType 
or VariableDeclaratorId, then the type of the local variable is specified by §10.2. 


¢ If LocalVariableType is var, then let rT be the type of the initializer expression 
when treated as if it did not appear in an assignment context, and were thus 
a standalone expression ($15.2). The type of the local variable is the upward 
projection of 7 with respect to all synthetic type variables mentioned by rT 
($4.10.5). 


It is a compile-time error if Tis the null type. 
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Because the initializer is treated as if it did not appear in an assignment context, an error 
occurs if it is a lambda expression (§15.27) or a method reference expression ($15.13). 


Example 14.4.1-1. Type of Local Variables Declared With var 


The following code illustrates the typing of variables declared with var: 


var a= 1; // a has type ‘int' 
var b = java.util.List.of(1, 2); // b has type 'List<Integer>' 
var c = "x".getClass(); // c has type 'Class<? extends String>! 


// (see JLS 15.12.2.6) 
var d = new Object() {}; // d has the type of the anonymous class 


14.4 


var e = (CharSequence & Comparable<String>) "x"; 

// e has type CharSequence & Comparable<String> 
var f = () -> "hello"; // T1llegal: lambda not in an assignment context 
var g = null; // Tllegal: null type 


Note that some variables declared with var cannot be declared with an explicit type, 
because the type of the variable is not denotable. 


Upward projection is applied to the type of the initializer when determining the type of the 
variable. If the type of the initializer contains capture variables, this projection maps the 
type of the initializer to a supertype that does not contain capture variables. 


While it would be possible to allow the type of the variable to mention capture variables, 
by projecting them away we enforce an attractive invariant that the scope of a capture 
variable is never larger than the statement containing the expression whose type is captured. 
Informally, capture variables cannot "leak" into subsequent statements. 


A local variable of type float always contains a value that is an element of the 
float value set (§4.2.3); similarly, a local variable of type double always contains 
a value that is an element of the double value set. It is not permitted for a local 
variable of type float to contain an element of the float-extended-exponent value 
set that is not also an element of the float value set, nor for a local variable of type 
double to contain an element of the double-extended-exponent value set that is not 
also an element of the double value set. 


The scope and shadowing of a local variable declaration is specified in $6.3 and 
$6.4. 


14.4.2 Execution of Local Variable Declarations 


A local variable declaration statement is an executable statement. Every time it is 
executed, the declarators are processed in order from left to right. If a declarator 
has an initializer, the initializer is evaluated and its value is assigned to the variable. 
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If a declarator does not have an initializer, then every reference to the variable must be 
preceded by execution of an assignment to the variable, or a compile-time error occurs by 
the rules of §16 (Definite Assignment). 


Each initializer (except the first) is evaluated only if evaluation of the preceding 
initializer completes normally. 


Execution of the local variable declaration completes normally only if evaluation 
of the last initializer completes normally. 


If the local variable declaration contains no initializers, then executing it always 
completes normally. 


14.5 Statements 


There are many kinds of statements in the Java programming language. Most 
correspond to statements in the C and C++ languages, but some are unique. 


As in C and C++, the if statement of the Java programming language suffers from 
the so-called "dangling else problem," illustrated by this misleadingly formatted 
example: 


if (door.isOpen () ) 
if (resident.isVisible() ) 
resident.greet ("Hello!"); 
else door.bell.ring(); // A "dangling else" 


The problem is that both the outer if statement and the inner if statement might 
conceivably own the else clause. In this example, one might surmise that the 
programmer intended the else clause to belong to the outer if statement. 


The Java programming language, like C and C++ and many programming 
languages before them, arbitrarily decrees that an else clause belongs to the 
innermost if to which it might possibly belong. This rule is captured by the 
following grammar: 


Statement: 
StatementWithoutTrailingSubstatement 
LabeledStatement 
IfThenStatement 
IfThenElseStatement 
WhileStatement 
ForStatement 
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StatementNoShortlf: 
StatementWithoutTrailingSubstatement 
LabeledStatementNoShortlf 
IfThenElseStatementNoShortlf 
WhileStatementNoShortlf 
ForStatementNoShortlf 


StatementWithoutTrailingSubstatement: 
Block 
EmptyStatement 
ExpressionStatement 
AssertStatement 
SwitchStatement 
DoStatement 
BreakStatement 
ContinueStatement 
ReturnStatement 
SynchronizedStatement 
ThrowStatement 
TryStatement 


The following productions from §14.9 are shown here for convenience: 


IfThenStatement: 
if ( Expression ) Statement 


IfThenElseStatement: 
if ( Expression ) StatementNoShortlf else Statement 


IfThenElseStatementNoShortIf: 
if ( Expression ) StatementNoShortlf else StatementNoShortlf 


Statements are thus grammatically divided into two categories: those that might 
end in an if statement that has no else clause (a "short if statement") and those 
that definitely do not. 


Only statements that definitely do not end in a short if statement may appear as 
an immediate substatement before the keyword else in an if statement that does 
have an else clause. 


This simple rule prevents the "dangling else" problem. The execution behavior of 
a statement with the "no short if" restriction is identical to the execution behavior 
of the same kind of statement without the "no short if" restriction; the distinction 
is drawn purely to resolve the syntactic difficulty. 
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14.6 The Empty Statement 


An empty statement does nothing. 


EmptyStatement: 


’ 


Execution of an empty statement always completes normally. 


14.7 Labeled Statements 


Statements may have /abel prefixes. 


LabeledStatement: 
Identifier : Statement 


LabeledStatementNoShortIf: 
Identifier : StatementNoShortlf 


The Identifier is declared to be the label of the immediately contained Statement. 


Unlike C and C++, the Java programming language has no goto statement; 
identifier statement labels are used with break or continue statements (§14.15, 
§14.16) appearing anywhere within the labeled statement. 


The scope of a label of a labeled statement is the immediately contained Statement. 


It is acompile-time error if the name of a label of a labeled statement is used within 
the scope of the label as a label of another labeled statement. 


There is no restriction against using the same identifier as a label and as the name 
of a package, class, interface, method, field, parameter, or local variable. Use of an 
identifier to label a statement does not obscure (§6.4.2) a package, class, interface, 
method, field, parameter, or local variable with the same name. Use of an identifier 
as aclass, interface, method, field, local variable or as the parameter of an exception 
handler ($14.20) does not obscure a statement label with the same name. 


A labeled statement is executed by executing the immediately contained Statement. 


If the statement is labeled by an /dentifier and the contained Statement completes 
abruptly because of a break with the same /dentifier, then the labeled statement 
completes normally. In all other cases of abrupt completion of the Statement, the 
labeled statement completes abruptly for the same reason. 
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Example 14.7-1. Labels and Identifiers 


The following code was taken from a version of the class St ring and its method indexoOf, 
where the label was originally called test. Changing the label to have the same name as 
the local variable i does not obscure the label in the scope of the declaration of i. Thus, 
the code is valid. 


class Test { 
char[] value; 
int offset, count; 
int indexOf(TestString str, int fromIndex) { 


char[] vl = value, v2 = str.value; 
int max = offset + (count —- str.count); 
int start = offset + ((fromIndex < 0) ? 0 : fromIndex); 
Hee: 

for (int i = start; i <= max; itt) { 

int n = str.count, j = i, k = str.offset; 

while (n-- != 0) { 

if (vl [j++] != v2[k++]) 


continue i; 
} 
return i - offset; 
} 


return -1; 


The identifier max could also have been used as the statement label; the label would not 
obscure the local variable max within the labeled statement. 


14.8 Expression Statements 


Certain kinds of expressions may be used as statements by following them with 
semicolons. 


ExpressionStatement: 
StatementExpression ; 
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StatementExpression: 
Assignment 
PreIncrementExpression 
PreDecrementExpression 
PostIncrementExpression 
PostDecrementExpression 
MethodInvocation 
ClassInstanceCreationExpression 


An expression statement is executed by evaluating the expression; if the expression 
has a value, the value is discarded. 


Execution of the expression statement completes normally if and only if evaluation 
of the expression completes normally. 


Unlike C and C++, the Java programming language allows only certain forms of 
expressions to be used as expression statements. For example, it is legal to use a method 
invocation expression (§15.12): 


System.out.printin("Hello world"); // OK 
but it is not legal to use a parenthesized expression (§15.8.5): 
(System.out.println("Hello world")); // illegal 


Note that the Java programming language does not allow a "cast to void" - void is not a 
type - so the traditional C trick of writing an expression statement such as: 


(void)... ; // incorrect! 


does not work. On the other hand, the Java programming language allows all the most useful 
kinds of expressions in expression statements, and it does not require a method invocation 
used as an expression statement to invoke a void method, so such a trick is almost never 
needed. If a trick is needed, either an assignment statement (§15.26) or a local variable 
declaration statement (§14.4) can be used instead. 


14.9 The it Statement 


The if statement allows conditional execution of a statement or a conditional 
choice of two statements, executing one or the other but not both. 


IfThenStatement: 
if ( Expression ) Statement 
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IfThenElseStatement: 
if ( Expression ) StatementNoShortlf e1se Statement 


IfThenElseStatementNoShortIf: 
if ( Expression ) StatementNoShortlf else StatementNoShortlf 


The Expression must have type boolean or Boolean, or a compile-time error 
occurs. 


14.9.1 The if-then Statement 


An if-then statement is executed by first evaluating the Expression. If the result 
is of type Boolean, it is subject to unboxing conversion (§5.1.8). 


If evaluation of the Expression or the subsequent unboxing conversion (if any) 
completes abruptly for some reason, the if-then statement completes abruptly for 
the same reason. 


Otherwise, execution continues by making a choice based on the resulting value: 


e If the value is true, then the contained Statement is executed; the if-then 
statement completes normally if and only if execution of the Statement completes 
normally. 


e If the value is false, no further action is taken and the if-then statement 
completes normally. 


14.9.2 The if-then-else Statement 


An if-then-else statement is executed by first evaluating the Expression. If the 
result is of type Boolean, it is subject to unboxing conversion (§5.1.8). 


If evaluation of the Expression or the subsequent unboxing conversion (if any) 
completes abruptly for some reason, then the if-then-else statement completes 
abruptly for the same reason. 


Otherwise, execution continues by making a choice based on the resulting value: 


¢ If the value is true, then the first contained Statement (the one before the else 
keyword) is executed; the if-then-else statement completes normally if and 
only if execution of that statement completes normally. 


¢ If the value is false, then the second contained Statement (the one after the else 
keyword) is executed; the if-then-else statement completes normally if and 
only if execution of that statement completes normally. 
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14.10 The assert Statement 


An assertion is an assert statement containing a boolean expression. An assertion 
is either enabled or disabled. If an assertion is enabled, execution of the assertion 
causes evaluation of the boolean expression and an error is reported if the 
expression evaluates to false. If the assertion is disabled, execution of the assertion 
has no effect whatsoever. 


AssertStatement: 
assert Expression ; 
assert Expression : Expression ; 


To ease the presentation, the first Expression in both forms of the assert statement 
is referred to as Expression!. In the second form of the assert statement, the 
second Expression is referred to as Expression2. 


It is a compile-time error if Expression! does not have type boolean Or Boolean. 


It is a compile-time error if, in the second form of the assert statement, 
Expression? is void (§15.1). 


An assert statement that is executed after its class or interface has completed 
initialization is enabled if and only if the host system has determined that the 
top level class or interface that lexically contains the assert statement enables 
assertions. 


Whether a top level class or interface enables assertions is determined no later 
than the earliest of (i) the initialization of the top level class or interface, and (ii) 
the initialization of any class or interface nested in the top level class or interface. 
Whether a top level class or interface enables assertions cannot be changed after 
it has been determined. 


An assert statement that is executed before its class or interface has completed 
initialization is enabled. 


This rule is motivated by a case that demands special treatment. Recall that the assertion 
status of a class is set no later than the time it is initialized. It is possible, though generally 
not desirable, to execute methods or constructors prior to initialization. This can happen 
when a class hierarchy contains a circularity in its static initialization, as in the following 
example: 


public class Foo { 
public static void main(String[] args) { 
Baz.testAsserts (); 
// Will execute after Baz is initialized. 
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} 
class Bar { 
static: 4 
Baz.testAsserts(); 
// Will execute before Baz is initialized! 


} 
class Baz extends Bar { 
static void testAsserts() { 
boolean enabled = false; 
assert enabled = true; 
System.out.println("Asserts " + 
(enabled ? "enabled" : "disabled")); 


Invoking Baz.testAsserts() causes Baz to be initialized. Before this can happen, Bar 
must be initialized. Bar's static initializer again invokes Baz.testAsserts (). Because 
initialization of Baz is already in progress by the current thread, the second invocation 
executes immediately, though Baz is not initialized (§12.4.2). 


Because of the rule above, if the program above is executed without enabling assertions, 
it must print: 


Asserts enabled 
Asserts disabled 


A disabled assert statement does nothing. In particular, neither Expression! 
nor Expression2 (if it is present) are evaluated. Execution of a disabled assert 
statement always completes normally. 


An enabled assert statement is executed by first evaluating Expression!. If the 
result is of type Boolean, it is subject to unboxing conversion (§5.1.8). 


If evaluation of Expression! or the subsequent unboxing conversion (if any) 
completes abruptly for some reason, the assert statement completes abruptly for 
the same reason. 


Otherwise, execution continues by making a choice based on the value of 
Expression: 


If the value is true, no further action is taken and the assert statement completes 
normally. 


If the value is false, the execution behavior depends on whether Expression2 
is present: 


— If Expression2 is present, it is evaluated. Then: 
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>» If the evaluation completes abruptly for some reason, the assert statement 
completes abruptly for the same reason. 


>» If the evaluation completes normally, an AssertionError instance whose 
"detail message” is the resulting value of Expression2 is created. Then: 


» If the instance creation completes abruptly for some reason, the assert 
statement completes abruptly for the same reason. 


» If the instance creation completes normally, the assert statement 
completes abruptly by throwing the newly created AssertionError 
object. 


— If Expression2 is not present, an AssertionError instance with no "detail 
message” is created. Then: 


>» If the instance creation completes abruptly for some reason, the assert 
statement completes abruptly for the same reason. 


>» Ifthe instance creation completes normally, the assert statement completes 
abruptly by throwing the newly created Assert ionError object. 


Typically, assertion checking is enabled during program development and testing, and 
disabled for deployment, to improve performance. 


Because assertions may be disabled, programs must not assume that the expressions 
contained in assertions will be evaluated. Thus, these boolean expressions should generally 
be free of side effects. Evaluating such a boolean expression should not affect any state 
that is visible after the evaluation is complete. It is not illegal for a boolean expression 
contained in an assertion to have a side effect, but it is generally inappropriate, as it could 
cause program behavior to vary depending on whether assertions were enabled or disabled. 


In light of this, assertions should not be used for argument checking in public methods. 
Argument checking is typically part of the contract of a method, and this contract must be 
upheld whether assertions are enabled or disabled. 


A secondary problem with using assertions for argument checking is_ that 
erroneous arguments should result in an appropriate run-time exception 
(such aS IllegalArgumentException, ArrayIndexOutOfBoundsException, or 
NullPointerException). An assertion failure will not throw an appropriate exception. 
Again, it is not illegal to use assertions for argument checking on public methods, but it 
is generally inappropriate. It is intended that AssertionError never be caught, but it is 
possible to do so, thus the rules for try statements should treat assertions appearing in a 
try block similarly to the current treatment of throw statements. 
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14.11 The switch Statement 


The switch statement transfers control to one of several statements depending on 
the value of an expression. 


SwitchStatement: 
switch ( Expression ) SwitchBlock 


SwitchBlock: 
{ {SwitchBlockStatementGroup} {SwitchLabel} } 


SwitchBlockStatementGroup: 
SwitchLabels BlockStatements 


SwitchLabels: 
SwitchLabel {SwitchLabel} 


SwitchLabel: 
case ConstantExpression : 
case EnumConstantName : 
default : 


EnumConstantName: 
Identifier 


The type of the Expression must be char, byte, short, int, Character, Byte, 
Short, Integer, String, or an enum type (§8.9), or a compile-time error occurs. 


The body of a switch statement is known as a switch block. Any statement 
immediately contained by the switch block may be labeled with one or more switch 
labels, which are case or default labels. Every case label has a case constant, 
which is either a constant expression or the name of an enum constant. Switch 
labels and their case constants are said to be associated with the switch statement. 


Given a switch Statement, all of the following must be true or a compile-time error 
occurs: 


e Every case constant associated with the switch statement must be assignment 
compatible with the type of the switch statement's Expression (§5.2). 


¢ If the type of the switch statement's Expression is an enum type, then every 
case constant associated with the switch statement must be an enum constant 
of that type. 
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¢ No two of the case constants associated with the switch statement have the 
same value. 


¢ No case constant associated with the switch statement is null. 


e At most one default label is associated with the switch statement. 


The prohibition against using null as a case constant prevents code being written that 
can never be executed. If the switch statement's Expression is of a reference type, that is, 
String or a boxed primitive type or an enum type, then an exception will be thrown will 
occur if the Expression evaluates to null at run time. In the judgment of the designers of 
the Java programming language, this is a better outcome than silently skipping the entire 
switch statement or choosing to execute the statements (if any) after the default label 
(if any). 


A Java compiler is encouraged (but not required) to provide a warning if a switch on an 
enum-valued expression lacks a default label and lacks case labels for one or more of 
the enum's constants. Such a switch will silently do nothing if the expression evaluates 
to one of the missing constants. 


In C and C++ the body of a switch statement can be a statement and statements with case 
labels do not have to be immediately contained by that statement. Consider the simple loop: 


for (i = 0; i < n; ++i) foo(); 


where n is known to be positive. A trick known as Duff's device can be used in C or C++ 
to unroll the loop, but this is not valid code in the Java programming language: 


int q = (n+7)/8; 
switch (n%8) { 
case 0: do { foo(); // Great C hack, Tom, 
case 7: foo(); // but it's not valid here. 
case 6: foo(); 
case 5: foo(); 
case 4: foo(); 
case 3: foo(); 
case 2: foo(); 
case l: foo(); 
} while (--q > 0); 


Fortunately, this trick does not seem to be widely known or used. Moreover, it is less needed 
nowadays; this sort of code transformation is properly in the province of state-of-the-art 
optimizing compilers. 


A switch statement is executed by first evaluating the Expression. If the 
Expression evaluates to null, a Nul1PointerException 1s thrown and the entire 
switch Statement completes abruptly for that reason. Otherwise, if the result is of 
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type Character, Byte, Short, Or Integer, it is subject to unboxing conversion 
(§5.1.8). 


If evaluation of the Expression or the subsequent unboxing conversion (if any) 
completes abruptly for some reason, the switch statement completes abruptly for 
the same reason. 


Otherwise, execution continues by comparing the value of the Expression with each 
case constant, and there is a choice: 


¢ If one of the case constants is equal to the value of the expression, then we 
say that the case label matches. Equality is defined in terms of the == operator 
($15.21) unless the value of the expression is a String, in which case equality 
is defined in terms of the equals method of class string. 


All statements after the matching case label in the switch block, if any, are 
executed in sequence. 


If all these statements complete normally, or if there are no statements after the 
matching case label, then the entire switch statement completes normally. 


¢ If no case label matches but there is a default label, then all statements after 
the default label in the switch block, if any, are executed in sequence. 


If all these statements complete normally, or if there are no statements after the 
default label, then the entire switch statement completes normally. 


¢ If no case label matches and there is no default label, then no further action is 
taken and the switch statement completes normally. 


If any statement immediately contained by the Block body of the switch statement 
completes abruptly, it is handled as follows: 


¢ If execution of the Statement completes abruptly because of a break with no 
label, no further action is taken and the switch statement completes normally. 


¢ If execution of the Statement completes abruptly for any other reason, the switch 
statement completes abruptly for the same reason. 


The case of abrupt completion because of a break with a label is handled by the general 
rule for labeled statements (§ 14.7). 


Example 14.11-1. Fall-Through in the switch Statement 
As in C and C++, execution of statements in a switch block "falls through labels." 
For example, the program: 


class TooMany { 
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static void howMany(int k) { 
switch (k) { 
case 1: System.out.print ("one "); 
case 2: System.out.print ("too "); 
case 3: System.out.printlin("many") ; 


} 

public static void main(String[] args) { 
howMany (3) ; 
howMany (2) ; 
howMany (1); 


contains a switch block in which the code for each case falls through into the code for 
the next case. As a result, the program prints: 


many 
too many 
one too many 


If code is not to fall through case to case in this manner, then break statements should 
be used, as in this example: 


class TwoMany { 
static void howMany(int k) { 
switch (k) { 

case 1: System.out.println("one") ; 
break; // exit the switch 

case 2: System.out.println ("two"); 
break; // exit the switch 

case 3: System.out.printlin("many") ; 
break; // not needed, but good style 


} 

public static void main(String[] args) { 
howMany (1); 
howMany (2) ; 
howMany (3) ; 


This program prints: 


one 
two 
many 
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14.12 The while Statement 


The while statement executes an Expression and a Statement repeatedly until the 
value of the Expression is false. 


WhileStatement: 
while ( Expression ) Statement 


WhileStatementNoShortIf: 
while ( Expression ) StatementNoShortlf 


The Expression must have type boolean or Boolean, or a compile-time error 
occurs. 


A while statement is executed by first evaluating the Expression. If the result is of 
type Boolean, it is subject to unboxing conversion (§5.1.8). 


If evaluation of the Expression or the subsequent unboxing conversion (if any) 
completes abruptly for some reason, the while statement completes abruptly for 
the same reason. 


Otherwise, execution continues by making a choice based on the resulting value: 


e If the value is true, then the contained Statement is executed. Then there is a 
choice: 


— If execution of the Statement completes normally, then the entire while 
statement is executed again, beginning by re-evaluating the Expression. 


— If execution of the Statement completes abruptly, see §14.12.1. 


¢ If the (possibly unboxed) value of the Expression is false, no further action is 
taken and the while statement completes normally. 


If the (possibly unboxed) value of the Expression is false the first time it is evaluated, 
then the Statement is not executed. 


14.12.1 Abrupt Completion of while Statement 


Abrupt completion of the contained Statement is handled in the following manner: 


¢ If execution of the Statement completes abruptly because of a break with no 
label, no further action is taken and the while statement completes normally. 


¢ If execution of the Statement completes abruptly because of a continue with no 
label, then the entire while statement is executed again. 
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¢ If execution of the Statement completes abruptly because of a continue with 
label 1, then there is a choice: 


— If the while statement has label 1, then the entire while statement is executed 
again. 


— If the while statement does not have label 1, the while statement completes 
abruptly because of a continue with label z. 


¢ If execution of the Statement completes abruptly for any other reason, the while 
statement completes abruptly for the same reason. 


The case of abrupt completion because of a break with a label is handled by the general 
rule for labeled statements (§ 14.7). 


14.13 The do Statement 


The do statement executes a Statement and an Expression repeatedly until the value 
of the Expression is false. 


DoStatement: 
do Statement while ( Expression ) ; 


The Expression must have type boolean or Boolean, or a compile-time error 
occurs. 
A do statement is executed by first executing the Statement. Then there is a choice: 


¢ If execution of the Statement completes normally, then the Expression is 
evaluated. If the result is of type Boolean, it is subject to unboxing conversion 
($5.1.8). 


If evaluation of the Expression or the subsequent unboxing conversion (if any) 
completes abruptly for some reason, the do statement completes abruptly for the 
same reason. 


Otherwise, there is a choice based on the resulting value: 
— If the value is true, then the entire do statement is executed again. 


— If the value is false, no further action is taken and the do statement completes 
normally. 


¢ If execution of the Statement completes abruptly, see §14.13.1. 


Executing a do statement always executes the contained Statement at least once. 
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14.13.1 Abrupt Completion of ao Statement 


Abrupt completion of the contained Statement is handled in the following manner: 


¢ If execution of the Statement completes abruptly because of a break with no 
label, then no further action is taken and the do statement completes normally. 


¢ If execution of the Statement completes abruptly because of a continue with 
no label, then the Expression is evaluated. Then there is a choice based on the 
resulting value: 


— If the value is true, then the entire do statement is executed again. 


— If the value is false, no further action is taken and the do statement completes 
normally. 


¢ If execution of the Statement completes abruptly because of a continue with 
label 1, then there is a choice: 


— If the do statement has label 1, then the Expression is evaluated. Then there 
is a choice: 


>» If the value of the Expression is true, then the entire do statement is 
executed again. 


>» If the value of the Expression is false, no further action is taken and the do 
statement completes normally. 


— If the do statement does not have label 1, the do statement completes abruptly 
because of a continue with label t. 


¢ If execution of the Statement completes abruptly for any other reason, the do 
statement completes abruptly for the same reason. 


The case of abrupt completion because of a break with a label is handled by the general 
rule for labeled statements (§ 14.7). 


Example 14.13-1. The do Statement 


The following code is one possible implementation of the toHexSt ring method of class 
Integer: 


public static String toHexString(int i) { 
StringBuffer buf = new StringBuffer (8); 
do { 
buf.append(Character.forDigit (i & OxF, 16)); 
i bos= 45 
} while (i != 0); 
return buf.reverse().toString(); 
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Because at least one digit must be generated, the do statement is an appropriate control 
structure. 


14.14 The for Statement 


The for statement has two forms: 

¢ The basic for statement. 

¢ The enhanced for statement 
ForStatement: 


BasicForStatement 
EnhancedForStatement 


ForStatementNoShortlf: 
BasicForStatementNoShortlf 
EnhancedForStatementNoShortlf 


14.14.1 The basic for Statement 


The basic for statement executes some initialization code, then executes an 
Expression, a Statement, and some update code repeatedly until the value of the 
Expression is false. 


BasicForStatement: 
for ([Forlnit] ; [Expression] ; [ForUpdate] ) Statement 


BasicForStatementNoShortlf: 
for ([ForInit] ; [Expression] ; [ForUpdate] ) StatementNoShortlf 


Forlnit: 
StatementExpressionList 
LocalVariableDeclaration 


ForUpdate: 
StatementExpressionList 


StatementExpressionList: 
StatementExpression {, StatementExpression} 
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The Expression must have type boolean or Boolean, or a compile-time error 
occurs. 


The scope and shadowing of a local variable declared in the ForInit part of a basic 
for statement is specified in §6.3 and §6.4. 


14.14.1.1 Initialization of for Statement 


A for statement is executed by first executing the ForInit code: 


If the ForInit code is a list of statement expressions ($14.8), the expressions are 
evaluated in sequence from left to right; their values, if any, are discarded. 


If evaluation of any expression completes abruptly for some reason, the for 
statement completes abruptly for the same reason; any Forlnit statement 
expressions to the right of the one that completed abruptly are not evaluated. 


If the ForInit code is a local variable declaration ($14.4), it is executed as if it 
were a local variable declaration statement appearing in a block. 


If execution of the local variable declaration completes abruptly for any reason, 
the for statement completes abruptly for the same reason. 


If the ForInit part is not present, no action is taken. 


14.14.1.2 Iteration of for Statement 


Next, a for iteration step is performed, as follows: 


If the Expression is present, it is evaluated. If the result is of type Boolean, it is 
subject to unboxing conversion (§5.1.8). 


If evaluation of the Expression or the subsequent unboxing conversion (if any) 
completes abruptly, the for statement completes abruptly for the same reason. 


Otherwise, there is then a choice based on the presence or absence of the Expression and 
the resulting value if the Expression is present; see next bullet. 


If the Expression is not present, or it is present and the value resulting from 


its evaluation (including any possible unboxing) is true, then the contained 
Statement is executed. Then there is a choice: 


— If execution of the Statement completes normally, then the following two steps 
are performed in sequence: 


1. First, if the ForUpdate part is present, the expressions are evaluated 
in sequence from left to right; their values, if any, are discarded. If 
evaluation of any expression completes abruptly for some reason, the 
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for statement completes abruptly for the same reason; any ForUpdate 
statement expressions to the right of the one that completed abruptly are 
not evaluated. 


If the ForUpdate part is not present, no action is taken. 
2. Second, another for iteration step is performed. 
— If execution of the Statement completes abruptly, see §14.14.1.3. 


¢ If the Expression is present and the value resulting from its evaluation (including 
any possible unboxing) is false, no further action is taken and the for statement 
completes normally. 


If the (possibly unboxed) value of the Expression is false the first time it is evaluated, 
then the Statement is not executed. 


If the Expression is not present, then the only way a for statement can complete 
normally is by use of a break statement. 


14.14.1.3. Abrupt Completion of for Statement 
Abrupt completion of the contained Statement is handled in the following manner: 


¢ If execution of the Statement completes abruptly because of a break with no 
label, no further action is taken and the for statement completes normally. 


¢ If execution of the Statement completes abruptly because of a continue with no 
label, then the following two steps are performed in sequence: 


1. First, if the ForUpdate part is present, the expressions are evaluated in 
sequence from left to right; their values, if any, are discarded. 


If the ForUpdate part is not present, no action is taken. 
2. Second, another for iteration step is performed. 


¢ If execution of the Statement completes abruptly because of a continue with 
label x, then there is a choice: 


— If the for statement has label z, then the following two steps are performed 
in sequence: 


1. First, if the ForUpdate part is present, the expressions are evaluated in 
sequence from left to right; their values, if any, are discarded. 


If the ForUpdate is not present, no action is taken. 


2. Second, another for iteration step is performed. 
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— If the for statement does not have label 1, the for statement completes 
abruptly because of a continue with label z. 


¢ If execution of the Statement completes abruptly for any other reason, the for 
statement completes abruptly for the same reason. 


Note that the case of abrupt completion because of a break with a label is handled by 
the general rule for labeled statements (§ 14.7). 


14.14.2 The enhanced for statement 


The enhanced for statement has the form: 


EnhancedForStatement: 
for ( {VariableModifier} LocalVariableType VariableDeclaratorld 
: Expression ) 
Statement 


EnhancedForStatementNoShortlf: 
for ( {VariableModifier} LocalVariableType VariableDeclaratorld 
: Expression ) 
StatementNoShortlf 


The following productions from §4.3, §8.3, §8.4.1, and §14.4 are shown here for 
convenience: 


VariableModifier: 
Annotation 
final 


LocalVariableType: 
UnannType 
var 


VariableDeclaratorld: 
Identifier [Dims] 


Dims: 
{Annotation} [| ] {{Annotation} [ ]} 


The header of the enhanced for statement declares a local variable, whose name 
is the identifier given by VariableDeclaratorId. 


If the keyword final appears at the start of the declaration, the variable being 
declared is a final variable (§4.12.4). 
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It is a compile-time error if the LocalVariableType is var and _ the 
VariableDeclaratorld has one or more bracket pairs. 


The type of the Expression must be a subtype of the raw type Iterable or an array 
type ($10.1), or a compile-time error occurs. 


The type of the local variable is determined as follows: 


¢ If LocalVariableType is an UnannType, and no bracket pairs appear in 
UnannType or VariableDeclaratorId, then UnannType denotes the type of the 
local variable. 


¢ If LocalVariableType is an UnannType, and bracket pairs appear in UnannType 
or VariableDeclaratorId, then the type of the local variable is specified by §10.2. 


¢ If LocalVariableType is var, then let r be derived from the type of the 
Expression, as follows: 


— If the Expression has an array type, then rT is the component type of the array 
type. 
— Otherwise, if the Expression has a type that is a subtype of Iterable<x>, for 


some type x, then Tis x. 


— Otherwise, the Expression has a type that is a subtype of the raw type 
Iterable, and Tis Object. 


The type of the local variable is the upward projection of T with respect to all 
synthetic type variables mentioned by r (§$4.10.5). 


The scope and shadowing of the local variable is specified in §6.3 and §6.4. 


When an enhanced for statement is executed, the local variable is initialized, on 
each iteration of the loop, to successive elements of the array or Iterable produced 
by the expression. The precise meaning of the enhanced for statement is given by 
translation into a basic for statement, as follows: 


¢ If the type of Expression is a subtype of Iterable, then the translation is as 
follows. 


If the type of Expression is a subtype of Iterable<x> for some type argument 
X, then let r be the type java.util.Iterator<x>; otherwise, let z be the raw 
type java.util.Iterator. 


The enhanced for statement is equivalent to a basic for statement of the form: 
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for (I #i = Expression.iterator(); #i.hasNext(); ) { 
{VariableModifier} TargetType Identifier = 
(TargetType) #i.next(); 
Statement 


} 


#i iS an automatically generated identifier that is distinct from any other 
identifiers (automatically generated or otherwise) that are in scope ($6.3) at the 
point where the enhanced for statement occurs. 


If the declared type of the local variable in the header of the enhanced for 
statement is a reference type, then TargetType is that declared type; otherwise, 
TargetType is the upper bound of the capture conversion (§5.1.10) of the type 
argument of I, or Object if ris raw. 


For example, this code: 


List<? extends Integer> l=... 
for (float i: 1) 


will be translated to: 


for (Iterator<Integer> #i = l.iterator(); #i-hasNext(); ) { 
float #10 = (Integer) #i.next (); 


¢ Otherwise, the Expression necessarily has an array type, T[1]. 


Let 1; ... Lm be the (possibly empty) sequence of labels immediately preceding 
the enhanced for statement. 


The enhanced for statement is equivalent to a basic for statement of the form: 


T[] #a = Expression; 

plage. SLiDis: 0 ceteane, «line 

for (int #i = 0; #1 < #a.length; #i++) { 
{VariableModifier} TargetType Identifier = #a[#il; 
Statement 


} 


#a and #i are automatically generated identifiers that are distinct from any other 
identifiers (automatically generated or otherwise) that are in scope at the point 
where the enhanced for statement occurs. 


TargetType is the declared type of the local variable in the header of the enhanced 
for statement. 
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Example 14.14-1. Enhanced for And Arrays 


The following program, which calculates the sum of an integer array, shows how enhanced 
for works for arrays: 


int sum(int[] a) { 
int sum = 0; 
for (int i: a) sum += i; 


return sum; 


Example 14.14-2. Enhanced for And Unboxing Conversion 


The following program combines the enhanced for statement with auto-unboxing to 
translate a histogram into a frequency table: 


Map<String, Integer> histogram = ...; 
double total = 0; 


(int i : histogram.values() ) 

total += i; 

(Map.Entry<String, Integer> e : histogram.entrySet () ) 
System.out.printin(e.getKey() + " " + e.getValue() / total); 


14.15 The break Statement 


A break Statement transfers control out of an enclosing statement. 


BreakStatement: 
break [Identifier] ; 


A break statement with no label attempts to transfer control to the innermost 
enclosing switch, while, do, or for statement of the immediately enclosing 
method or initializer; this statement, which is called the break target, then 
immediately completes normally. 


To be precise, a break statement with no label always completes abruptly, the 
reason being a break with no label. 


If no switch, while, do, or for statement in the immediately enclosing method, 
constructor, or initializer contains the break statement, a compile-time error 


A break statement with label /dentifier attempts to transfer control to the enclosing 
labeled statement (§14.7) that has the same /dentifier as its label; this statement, 
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which is called the break target, then immediately completes normally. In this case, 
the break target need not be a switch, while, do, or for statement. 


To be precise, a break statement with label /dentifier always completes abruptly, 
the reason being a break with label Identifier. 


A break statement must refer to a label within the immediately enclosing method, 
constructor, initializer, or lambda body. There are no non-local jumps. If no 
labeled statement with Identifier as its label in the immediately enclosing method, 
constructor, initializer, or lambda body contains the break statement, a compile- 
time error occurs. 


It can be seen, then, that a break statement always completes abruptly. 


The preceding descriptions say "attempts to transfer control" rather than just "transfers 
control" because if there are any t ry statements (§14.20) within the break target whose try 
blocks or catch clauses contain the break statement, then any finally clauses of those 
try statements are executed, in order, innermost to outermost, before control is transferred 
to the break target. Abrupt completion of a finally clause can disrupt the transfer of 
control initiated by a break statement. 


Example 14.15-1. The break Statement 


In the following example, a mathematical graph is represented by an array of arrays. A 
graph consists of a set of nodes and a set of edges; each edge is an arrow that points from 
some node to some other node, or from a node to itself. In this example it is assumed that 
there are no redundant edges; that is, for any two nodes P and Q, where Q may be the same 
as P, there is at most one edge from P to oO. 


Nodes are represented by integers, and there is an edge from node i to node edges [i] 
[3] for every i and j for which the array reference edges[i][j] does not throw an 
ArrayIndexOutOfBoundsException 


The task of the method loseEdges, given integers i and j, is to construct a new graph by 
copying a given graph but omitting the edge from node i to node j, if any, and the edge 
from node j to node i, if any: 


class Graph { 
int edges[][]; 
public Graph(int[][] edges) { this.edges = edges; } 


public Graph loseEdges(int i, int j) { 
int n = edges.length; 


int[][] newedges = new int[n][]; 
for (int k = 0; k < n; ++k) { 
edgelist: 
{ 
int z; 


search: 
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if (k == i) { 
for (z = 0; z < edges[k].length; ++z) { 
if (edges[k][z] == j) break search; 
} 
} else if (k == 5) { 
for (z = 0; z < edges[k].length; ++z) { 
if (edges[k][z] == i) break search; 


// No edge to be deleted; share this list. 


newedges[k] = edges[k]; 
break edgelist; 

} //search 
// Copy the list, omitting the edge at position z. 
int m = edges[k].length - 1; 
int ne[] = new int[m]; 
System.arraycopy(edges[k], 0, ne, 0, Zz); 
System.arraycopy(edges[k], zt+l, ne, z, m-z); 
newedges[k] = ne; 

} //edgelist 


} 


return new Graph (newedges) ; 


Note the use of two statement labels, edgelist and search, and the use of break 
statements. This allows the code that copies a list, omitting one edge, to be shared between 
two separate tests, the test for an edge from node i to node j, and the test for an edge from 
node j to node i. 


14.16 The continue Statement 


A continue statement may occur only in a while, do, or for statement; statements 
of these three kinds are called iteration statements. Control passes to the loop- 
continuation point of an iteration statement. 


ContinueStatement: 
continue [Identifier] ; 


A continue statement with no label attempts to transfer control to the innermost 
enclosing while, do, or for statement of the immediately enclosing method, 
constructor, or initializer; this statement, which is called the continue target, then 
immediately ends the current iteration and begins a new one. 
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To be precise, such a continue statement always completes abruptly, the reason 
being a continue with no label. 


If no while, do, or for statement of the immediately enclosing method, constructor, 
or initializer contains the continue statement, a compile-time error occurs. 


A continue statement with label /dentifier attempts to transfer control to the 
enclosing labeled statement (§14.7) that has the same /dentifier as its label; that 
statement, which is called the continue target, then immediately ends the current 
iteration and begins a new one. 


To be precise, a continue statement with label Identifier always completes 
abruptly, the reason being a continue with label Identifier. 


The continue target must be a while, do, or for statement, or a compile-time error 
occurs. 


A continue statement must refer to a label within the immediately enclosing 
method, constructor, initializer, or lambda body. There are no non-local jumps. 
If no labeled statement with /dentifier as its label in the immediately enclosing 
method, constructor, initializer, or lambda body contains the continue statement, 
a compile-time error occurs. 


It can be seen, then, that a cont inue statement always completes abruptly. 


See the descriptions of the while statement (§14.12), do statement (§14.13), and for 
statement (§14.14) for a discussion of the handling of abrupt termination because of 
continue. 


The preceding descriptions say "attempts to transfer control" rather than just "transfers 
control" because if there are any try statements (§14.20) within the continue target whose 
try blocks or catch clauses contain the continue statement, then any finally clauses 
of those try statements are executed, in order, innermost to outermost, before control is 
transferred to the continue target. Abrupt completion of a finally clause can disrupt the 
transfer of control initiated by a cont inue statement. 


Example 14.16-1. The cont inue Statement 


In the Graph class in §14.15, one of the break statements is used to finish execution of 
the entire body of the outermost for loop. This break can be replaced by a continue if 
the for loop itself is labeled: 


class Graph { 
int edges[][]; 
public Graph(int[][] edges) { this.edges = edges; } 


public Graph loseEdges(int i, int j) { 
int n = edges.length; 
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int[][] newedges = new int[n][]; 
edgelists: 
for (int k = 0; k < n; ++k) { 
int z; 
search: 
{ 
if (k == i) { 
for (z = 0; z < edges[k].length; ++z) { 
if (edges[k][z] == j) break search; 
} 
} else if (k == 5) { 
for (z = 0; z < edges[k].length; ++z) { 
if (edges[k][z] == i) break search; 


// No edge to be deleted; share this list. 
newedges[k] = edges[k]; 
continue edgelists; 

} //search 


// Copy the list, omitting the edge at position z. 
int m = edges[k]-.length - 1; 
int ne[] = new int[m]; 
System.arraycopy(edges[k], 0, ne, 0, z); 
System.arraycopy(edges[k], zt+l, ne, z, m-z); 
newedges[k] = ne; 

} //edgelists 

return new Graph (newedges) ; 


Which to use, if either, is largely a matter of programming style. 


14.17 The return Statement 


A return statement returns control to the invoker of a method (§8.4, §15.12) or 
constructor (§8.8, §15.9). 


ReturnStatement: 
return [Expression] ; 


A return Statement is contained in the innermost constructor, method, initializer, 
or lambda expression whose body encloses the return statement. 


It is acompile-time error if a return statement is contained in an instance initializer 
or a Static initializer (§8.6, §8.7). 
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A return statement with no Expression must be contained in one of the following, 
or a compile-time error occurs: 


¢ A method that is declared, using the keyword void, not to return a value (§8.4.5) 
¢ A constructor (§8.8.7) 
¢ A lambda expression ($15.27) 


A return statement with no Expression attempts to transfer control to the invoker 
of the method, constructor, or lambda body that contains it. To be precise, a return 
statement with no Expression always completes abruptly, the reason being a return 
with no value. 


A return statement with an Expression must be contained in one of the following, 
or a compile-time error occurs: 


¢ A method that is declared to return a value 
e A lambda expression 
The Expression must denote a variable or a value, or a compile-time error occurs. 


When a return statement with an Expression appears in a method declaration, the 
Expression must be assignable (§5.2) to the declared return type of the method, or 
a compile-time error occurs. 


A return statement with an Expression attempts to transfer control to the invoker 
of the method or lambda body that contains it; the value of the Expression 
becomes the value of the method invocation. More precisely, execution of such a 
return Statement first evaluates the Expression. If the evaluation of the Expression 
completes abruptly for some reason, then the return statement completes abruptly 
for that reason. If evaluation of the Expression completes normally, producing a 
value v, then the return statement completes abruptly, the reason being a return 
with value v. 


If the expression is of type float and is not FP-strict ($15.4), then the value may 
be an element of either the float value set or the float-extended-exponent value set 
($4.2.3). If the expression is of type double and is not FP-strict, then the value 
may be an element of either the double value set or the double-extended-exponent 
value set. 


It can be seen, then, that a return statement always completes abruptly. 


The preceding descriptions say "attempts to transfer control" rather than just "transfers 
control" because if there are any try statements (§ 14.20) within the method or constructor 
whose try blocks or catch clauses contain the return statement, then any finally 
clauses of those try statements will be executed, in order, innermost to outermost, before 
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control is transferred to the invoker of the method or constructor. Abrupt completion of a 
finally clause can disrupt the transfer of control initiated by a return statement. 


14.18 The throw Statement 


A throw statement causes an exception (§11 (Exceptions)) to be thrown. The 
result is an immediate transfer of control ($11.3) that may exit multiple statements 
and multiple constructor, instance initializer, static initializer and field initializer 
evaluations, and method invocations until a try statement (§14.20) is found that 
catches the thrown value. If no such try statement is found, then execution of the 
thread ($17 (Threads and Locks)) that executed the throw is terminated ($11.3) 
after invocation of the uncaughtException method for the thread group to which 
the thread belongs. 


ThrowStatement: 
throw Expression ; 


The Expression in a throw statement must either denote a variable or value of a 
reference type which is assignable (§5.2) to the type Throwable, or denote the null 
reference, or a compile-time error occurs. 


The reference type of the Expression will always be a class type (since no interface types 
are assignable to Throwable) which is not parameterized (since a subclass of Throwable 
cannot be generic (§8.1.2)). 


At least one of the following three conditions must be true, or a compile-time error 
occurs: 


¢ The type of the Expression is an unchecked exception class (§11.1.1) or the null 
type (§4.1). 


e The throw statement is contained in the try block of a try statement (§14.20) 
and it is not the case that the try statement can throw an exception of the type 
of the Expression. (In this case we say the thrown value is caught by the try 
statement.) 


¢ The throw statement is contained in a method or constructor declaration and the 
type of the Expression is assignable (§5.2) to at least one type listed in the throws 
clause (§8.4.6, §8.8.5) of the declaration. 


The exception types that a throw statement can throw are specified in §11.2.2. 


A throw Statement first evaluates the Expression. Then: 
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¢ If evaluation of the Expression completes abruptly for some reason, then the 
throw completes abruptly for that reason. 


¢ If evaluation of the Expression completes normally, producing a non-nu11 value 
v, then the throw statement completes abruptly, the reason being a throw with 
value v. 


¢ If evaluation of the Expression completes normally, producing a nu11 value, then 
an instance v’' of class NullPointerException is created and thrown instead of 
null. The throw statement then completes abruptly, the reason being a throw 
with value v’. 


It can be seen, then, that a throw statement always completes abruptly. 


If there are any enclosing try statements ($14.20) whose try blocks contain the 
throw statement, then any finally clauses of those try statements are executed 
as control is transferred outward, until the thrown value is caught. Note that abrupt 
completion of a finally clause can disrupt the transfer of control initiated by a 
throw Statement. 


If a throw statement is contained in a method declaration or a lambda expression, 
but its value is not caught by some t ry statement that contains it, then the invocation 
of the method completes abruptly because of the throw. 


If a throw statement is contained in a constructor declaration, but its value is not 
caught by some try statement that contains it, then the class instance creation 
expression that invoked the constructor will complete abruptly because of the 
throw (§15.9.4). 


If a throw statement is contained in a static initializer ($8.7), then a compile-time 
check (§11.2.3) ensures that either its value is always an unchecked exception or 
its value is always caught by some try statement that contains it. If at run time, 
despite this check, the value is not caught by some try statement that contains the 
throw Statement, then the value is rethrown if it is an instance of class Error or one 
of its subclasses; otherwise, it is wrapped in an ExceptionInInitializerError 
object, which is then thrown (§12.4.2). 


If a throw statement is contained in an instance initializer (§8.6), then a compile- 
time check ($11.2.3) ensures that either its value is always an unchecked exception 
or its value is always caught by some try statement that contains it, or the type 
of the thrown exception (or one of its superclasses) occurs in the throws clause of 
every constructor of the class. 


By convention, user-declared throwable types should usually be declared to be subclasses 
of class Exception, which is a subclass of class Throwable (§11.1.1). 
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14.19 The synchronized Statement 


A synchronized statement acquires a mutual-exclusion lock (§17.1) on behalf of 
the executing thread, executes a block, then releases the lock. While the executing 
thread owns the lock, no other thread may acquire the lock. 


SynchronizedStatement: 
synchronized ( Expression ) Block 


The type of Expression must be a reference type, or a compile-time error occurs. 
A synchronized statement is executed by first evaluating the Expression. Then: 


¢ If evaluation of the Expression completes abruptly for some reason, then the 
synchronized statement completes abruptly for the same reason. 


¢ Otherwise, if the value of the Expression is null, a Nul1PointerException iS 
thrown. 


¢ Otherwise, let the non-nu11 value of the Expression be v. The executing thread 
locks the monitor associated with v. Then the Block is executed, and then there 
is a choice: 


— If execution of the Block completes normally, then the monitor is unlocked 
and the synchronized statement completes normally. 


— If execution of the Block completes abruptly for any reason, then the monitor 
is unlocked and the synchronized statement completes abruptly for the same 
reason. 


The locks acquired by synchronized statements are the same as the locks that 
are acquired implicitly by synchronized methods (§8.4.3.6). A single thread may 
acquire a lock more than once. 


Acquiring the lock associated with an object does not in itself prevent other threads 
from accessing fields of the object or invoking un-synchronized methods on the 
object. Other threads can also use synchronized methods or the synchronized 
statement in a conventional manner to achieve mutual exclusion. 


Example 14.19-1. The synchronized Statement 


class Test { 
public static void main(String[] args) { 
Test t = new Test(); 
synchronized(t) { 
synchronized(t) { 
System.out.println("made it!"); 
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} 
This program produces the output: 
made it! 


Note that this program would deadlock if a single thread were not permitted to lock a 
monitor more than once. 


14.20 The try statement 


A try statement executes a block. If a value is thrown and the try statement has 
one or more catch clauses that can catch it, then control will be transferred to the 
first such catch clause. If the try statement has a finally clause, then another 
block of code is executed, no matter whether the try block completes normally or 
abruptly, and no matter whether a catch clause is first given control. 


TryStatement: 
try Block Catches 
try Block [Catches] Finally 
TryWithResourcesStatement 


Catches: 
CatchClause {CatchClause} 


CatchClause: 
catch ( CatchFormalParameter ) Block 


CatchFormalParameter: 
{VariableModifier} CatchType VariableDeclaratorId 


CatchType: 
UnannClassType {| ClassType} 


Finally: 
finally Block 


See §8.3 for UnannClassType. The following productions from §4.3, §8.3, and §8.4.1 are 
shown here for convenience: 
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VariableModifier: 
Annotation 
final 


VariableDeclaratorld: 
Identifier [Dims] 


Dims: 
{Annotation} [| ] {{Annotation} [ ]} 


The Block immediately after the keyword try is called the try block of the try 
statement. 


The Block immediately after the keyword finally is called the finally block of 
the try statement. 


A try statement may have catch clauses, also called exception handlers. 


A catch clause declares exactly one parameter, which is called an exception 
parameter. 


It is a compile-time error if final appears more than once as a modifier for an 
exception parameter declaration. 


The scope and shadowing of an exception parameter is specified in $6.3 and §6.4. 


An exception parameter may denote its type as either a single class type or a union 
of two or more class types (called alternatives). The alternatives of a union are 
syntactically separated by |. 


A catch clause whose exception parameter is denoted as a single class type is 
called a uni-catch clause. 


A catch Clause whose exception parameter is denoted as a union of types is called 
a multi-catch clause. 


Each class type used in the denotation of the type of an exception parameter must 
be the class Throwable or a subclass of Throwable, or a compile-time error occurs. 


It is a compile-time error if a type variable is used in the denotation of the type of 
an exception parameter. 


It is a compile-time error if a union of types contains two alternatives p; and D; (i 
#j) where p; is a subtype of p, ($4.10.2). 


The declared type of an exception parameter that denotes its type with a single class 
type is that class type. 


The declared type of an exception parameter that denotes its type as a union with 
alternatives D; | Dz |... | D, 1s lub(D:, Dz, ..., Dn). 
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An exception parameter of a multi-catch clause is implicitly declared final if it 
is not explicitly declared final. 


It is a compile-time error if an exception parameter that is implicitly or explicitly 
declared final is assigned to within the body of the catch clause. 


An exception parameter of a uni-catch clause is never implicitly declared final, 
but it may be explicitly declared final or be effectively final (§4.12.4). 


An implicitly final exception parameter is final by virtue of its declaration, while an 
effectively final exception parameter is (as it were) final by virtue of how it is used. An 
exception parameter of a multi-catch clause is implicitly declared final, so will never 
occur as the left-hand operand of an assignment operator, but it is not considered effectively 
final. 


If an exception parameter is effectively final (in a uni-catch clause) or implicitly final 
(in a multi-catch clause), then adding an explicit final modifier to its declaration will 
not introduce any compile-time errors. On the other hand, if the exception parameter 
of a uni-catch clause is explicitly declared final, then removing the final modifier 
may introduce compile-time errors because the exception parameter, now considered to 
be effectively final, can no longer longer be referenced by anonymous and local class 
declarations in the body of the catch clause. If there are no compile-time errors, it is 
possible to further change the program so that the exception parameter is re-assigned in the 
body of the catch clause and thus will no longer be considered effectively final. 


The exception types that a try statement can throw are specified in $11.2.2. 


The relationship of the exceptions thrown by the try block of a try statement and 
caught by the catch clauses (if any) of the try statement is specified in §11.2.3. 


Exception handlers are considered in left-to-right order: the earliest possible catch 
clause accepts the exception, receiving as its argument the thrown exception object, 
as specified in $11.3. 


A multi-catch clause can be thought of as a sequence of uni-catch clauses. That is, a 
catch clause where the type of the exception parameter is denoted as a union D, | D2|...| Dp 
is equivalent to a sequence of n catch clauses where the types of the exception parameters 
are class types Dj, Do, ..., Dn respectively. In the Block of each of the n catch clauses, the 
declared type of the exception parameter is lub(D;, Dz, ..., D,). For example, the following 


code: 
try { 
. throws ReflectiveOperationException ... 
} 
catch (ClassNotFoundException | IllegalAccessException ex) { 


~ body «.. 
} 


is semantically equivalent to the following code: 
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try { 
. throws ReflectiveOperationException ... 
} 
catch (final ClassNotFoundException exl) { 
final ReflectiveOperationException ex = exl; 
- body ... 
} 
catch (final IllegalAccessException ex2) { 
final ReflectiveOperationException ex = ex2; 
- body ... 


where the multi-cat ch clause with two alternatives has been translated into two uni-cat ch 
clauses, one for each alternative. A Java compiler is neither required nor recommended to 
compile a multi-catch clause by duplicating code in this manner, since it is possible to 
represent the multi-catch clause in a class file without duplication. 


A finally clause ensures that the finally block is executed after the try block 
and any catch block that might be executed, no matter how control leaves the try 
block or catch block. Handling of the finally block is rather complex, so the two 
cases of a try statement with and without a finally block are described separately 
($14.20.1, $14.20.2). 


A try statement is permitted to omit catch clauses and a finally clause if it is a 
try-with-resources statement (§14.20.3). 


14.20.1 Execution of try-catch 


A try statement without a finally block is executed by first executing the try 
block. Then there is a choice: 


¢ If execution of the try block completes normally, then no further action is taken 
and the try statement completes normally. 


¢ If execution of the try block completes abruptly because of a throw of a value 
v, then there is a choice: 


— If the run-time type of v is assignment compatible with (§5.2) a catchable 
exception class of any catch clause of the try statement, then the first 
(leftmost) such catch clause is selected. The value v is assigned to the 
parameter of the selected catch clause, and the Block of that catch clause is 
executed, and then there is a choice: 


>» If that block completes normally, then the try statement completes 
normally. 
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>» If that block completes abruptly for any reason, then the try statement 
completes abruptly for the same reason. 


— If the run-time type of v is not assignment compatible with a catchable 
exception class of any catch clause of the try statement, then the try 
statement completes abruptly because of a throw of the value v. 


¢ If execution of the try block completes abruptly for any other reason, then the 
try Statement completes abruptly for the same reason. 


Example 14.20.1-1. Catching An Exception 


class BlewIt extends Exception { 
BlewIt() { } 
BlewIt (String s) { super(s); } 
} 


class Test: { 
static void blowUp() throws BlewIt { throw new BlewIt(); } 


public static void main(String[] args) { 
try { 
blowUp (); 
} catch (RuntimeException r) { 
System.out.println("Caught RuntimeException") ; 
} catch (BlewIt b) { 
System.out.println("Caught BlewIt"); 


} 


Here, the exception BlewIt is thrown by the method blowUp. The try-catch statement 
in the body of main has two catch clauses. The run-time type of the exception is BlewIt 
which is not assignable to a variable of type Runt imeException, but is assignable to a 
variable of type BlewIt, so the output of the example is: 


Caught BlewIt 


14.20.2 Execution of try-finally and try-catch-finally 


A try statement with a finally block is executed by first executing the try block. 
Then there is a choice: 


¢ If execution of the try block completes normally, then the finally block is 
executed, and then there is a choice: 


— If the finally block completes normally, then the try statement completes 
normally. 
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— If the finally block completes abruptly for reason s, then the try statement 
completes abruptly for reason s. 


¢ If execution of the try block completes abruptly because of a throw of a value 
v, then there is a choice: 


— If the run-time type of vis assignment compatible with a catchable exception 
class of any catch clause of the try statement, then the first (leftmost) such 
catch clause is selected. The value v is assigned to the parameter of the 
selected catch clause, and the Block of that catch clause is executed. Then 
there is a choice: 


>» Ifthe catch block completes normally, then the finally block is executed. 
Then there is a choice: 


» If the finally block completes normally, then the try statement 
completes normally. 


» If the finally block completes abruptly for any reason, then the try 
statement completes abruptly for the same reason. 


>» If the catch block completes abruptly for reason p, then the finally block 
is executed. Then there is a choice: 


» If the finally block completes normally, then the try statement 
completes abruptly for reason R. 


» If the finally block completes abruptly for reason s, then the try 
statement completes abruptly for reason s (and reason R is discarded). 


— If the run-time type of v is not assignment compatible with a catchable 
exception class of any catch clause of the try statement, then the finally 
block is executed. Then there is a choice: 


>» Ifthe finally block completes normally, then the try statement completes 
abruptly because of a throw of the value v. 


>» Ifthe finally block completes abruptly for reason s, then the try statement 
completes abruptly for reason s (and the throw of value vis discarded and 
forgotten). 


¢ If execution of the try block completes abruptly for any other reason pr, then the 
finally block is executed, and then there is a choice: 


— If the finally block completes normally, then the try statement completes 
abruptly for reason R. 
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— If the finally block completes abruptly for reason s, then the try statement 
completes abruptly for reason s (and reason R is discarded). 


Example 14.20.2-1. Handling An Uncaught Exception With finally 


class BlewIt extends Exception { 
BlewIt() { } 
BlewIt (String s) { super(s); } 
} 
class Test { 
static void blowUp() throws BlewIt { 
throw new NullPointerException (); 
} 
public static void main(String[] args) { 
try { 
blowUp (); 
} catch (BlewIt b) { 
System.out.printiln("Caught BlewIt"); 
} finally { 
System.out.println("Uncaught Exception") ; 


This program produces the output: 


Uncaught Exception 

Exception in thread "main" java.lang.NullPointerException 
at Test.blowUp (Test. Jjava:7) 
at Test.main(Test.java:11) 


The NullPointerException (which is a kind of RuntimeException) that is 
thrown by method blowUp is not caught by the try statement in main, because a 
NullPointerExcept ion is not assignable to a variable of type BlewIt. This causes the 
finally clause to execute, after which the thread executing main, which is the only thread 
of the test program, terminates because of an uncaught exception, which typically results in 
printing the exception name and a simple backtrace. However, a backtrace is not required 
by this specification. 


The problem with mandating a backtrace is that an exception can be created at one point in 
the program and thrown at a later one. It is prohibitively expensive to store a stack trace in 
an exception unless it is actually thrown (in which case the trace may be generated while 
unwinding the stack). Hence we do not mandate a back trace in every exception. 


14.20.3 try-with-resources 


A try-with-resources statement is parameterized with local variables (known 
as resources) that are initialized before execution of the try block and closed 
automatically, in the reverse order from which they were initialized, after execution 
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of the try block. catch clauses and a finally clause are often unnecessary when 
resources are closed automatically. 


TryWithResourcesStatement: 
try ResourceSpecification Block [Catches] [Finally] 


ResourceSpecification: 
( ResourceList [; ] ) 


ResourceList: 
Resource {; Resource} 


Resource: 
{VariableModifier} LocalVariableType Identifier = Expression 
VariableAccess 


VariableAccess: 
ExpressionName 
FieldAccess 


The following productions from §8.4.1 and §14.4 are shown here for convenience: 


VariableModifier: 
Annotation 
final 


LocalVariableType: 
UnannType 
var 


A resource specification uses variables to denote resources for the try statement, 
either by declaring local variables with initializer expressions or by referring 
to suitable existing variables. An existing variable is referred to by either an 
expression name (§6.5.6) or a field access expression (§15.11). 


It is a compile-time error for a resource specification to declare two variables with 
the same name. 


It is a compile-time error if final appears more than once as a modifier for each 
variable declared in a resource specification. 


A variable declared in a resource specification is implicitly declared final if it is 
not explicitly declared final ($4.12.4). 
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A resource denoted by an expression name or field access expression must be a 
final or effectively final variable that is definitely assigned before the t ry-with- 
resources statement (§16 (Definite Assignment)), or a compile-time error occurs. 


It is a compile-time error if the LocalVariableType of a variable declared in a 
resource specification is var and the initializer expression contains a reference to 
the variable. 


The type of a variable declared in a resource specification is determined as follows: 


¢ If LocalVariableType is an UnannType, then UnannType denotes the type of the 
local variable. 


¢ If LocalVariableType is var, then let rT be the type of the initializer expression 
when treated as if it did not appear in an assignment context, and were thus 
a standalone expression ($15.2). The type of the local variable is the upward 
projection of rT with respect to all synthetic type variables mentioned by rT 
($4.10.5). 


It is a compile-time error if Tis the null type. 


The type of a variable declared or referred to as a resource in a resource 
specification must be a subtype of AutoCloseable, or a compile-time error occurs. 


The scope and shadowing of a variable declared in a resource specification is 
specified in §6.3 and §6.4. 


Resources are initialized in left-to-right order. If a resource fails to initialize (that is, 
its initializer expression throws an exception), then all resources initialized so far by 
the try-with-resources statement are closed. If all resources initialize successfully, 
the try block executes as normal and then all non-null resources of the t ry-with- 
resources statement are closed. 


Resources are closed in the reverse order from that in which they were initialized. 
A resource is closed only if it initialized to a non-null value. An exception from 
the closing of one resource does not prevent the closing of other resources. Such 
an exception is suppressed if an exception was thrown previously by an initializer, 
the try block, or the closing of a resource. 


A try-with-resources statement whose resource specification indicates multiple 
resources is treated as if it were multiple try-with-resources statements, each of 
which has a resource specification that indicates a single resource. When a try- 
with-resources statement with n resources (n > 1) is translated, the result is a try- 
with-resources statement with n-1 resources. After n such translations, there are n 
nested try-catch-finally statements, and the overall translation is complete. 
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14.20.3.1 Basic try-with-resources 


A try-with-resources statement with no catch clauses or finally clause is called 
a basic try-with-resources statement. 


If a basic try-with-resource statement is of the form: 


try (VariableAccess ...) 
Block 


then the resource is first converted to a local variable declaration by the following 
translation: 


try (T #xr = VariableAccess ...) { 
Block 
} 


T is the type of the variable denoted by VariableAccess and #r is an automatically 
generated identifier that is distinct from any other identifiers (automatically 
generated or otherwise) that are in scope at the point where the t ry-with-resources 
statement occurs. The t ry-with-resources statement is then translated according to 
the rest of this section. 


The meaning of a basic try-with-resources statement of the form: 


try ({VariableModifier} R Identifier = Expression ...) 
Block 


is given by the following translation to a local variable declaration and at ry-cat ch- 
finally statement: 
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final {VariableModifierNoFinal} R Identifier = Expression; 
Throwable #primaryExc = null; 


try ResourceSpecification_tail 
Block 

catch (Throwable #t) { 
#primaryExc = #t; 


throw #t; 
} finally { 
if (Identifier != null) { 
if (#primaryExc != null) { 
try { 


Identifier.close(); 
} catch (Throwable #suppressedExc) { 
#primaryExc.addSuppressed (#suppressedExc) ; 


} 
} else { 
Identifier.close(); 


} 


} 


{VariableModifierNoFinal} is defined as {VariableModifier} without final, if 
present. 


#t, #primaryExc, and #suppressedExc are automatically generated identifiers that 
are distinct from any other identifiers (automatically generated or otherwise) that 
are in scope at the point where the t ry-with-resources statement occurs. 


If the resource specification indicates one resource, then 
ResourceSpecification_tail is empty (and the try-catch-finally statement is not 
itself a try-with-resources statement). 


If the resource specification indicates nm > 1 _ resources, then 
ResourceSpecification_tail consists of the 2nd, 3rd, ..., n'th resources indicated in 
the resource specification, in the same order (and the try-catch-finally statement 
is itself a try-with-resources statement). 


Reachability and definite assignment rules for the basic try-with-resources 
statement are implicitly specified by the translation above. 


In a basic t ry-with-resources statement that manages a single resource: 


¢ If the initialization of the resource completes abruptly because of a throw of a 
value v, then the try-with-resources statement completes abruptly because of a 
throw Of the value v. 
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e If the initialization of the resource completes normally, and the try block 
completes abruptly because of a throw of a value v, then: 


— If the automatic closing of the resource completes normally, then the t ry-with- 
resources statement completes abruptly because of a throw of the value v. 


— If the automatic closing of the resource completes abruptly because of a 
throw of a value v2, then the try-with-resources statement completes abruptly 
because of a throw of value v with v2 added to the suppressed exception list 
of v. 


e If the initialization of the resource completes normally, and the try block 
completes normally, and the automatic closing of the resource completes 
abruptly because of a throw of a value v, then the try-with-resources statement 
completes abruptly because of a throw of the value v. 


In a basic t ry-with-resources statement that manages multiple resources: 


¢ If the initialization of a resource completes abruptly because of a throw of a 
value v, then: 


— If the automatic closings of all successfully initialized resources (possibly 
zero) complete normally, then the try-with-resources statement completes 
abruptly because of a throw of the value v. 


— If the automatic closings of all successfully initialized resources (possibly 
zero) complete abruptly because of throws of values vi...vn, then the try- 
with-resources statement completes abruptly because of a throw of the value v 
with any remaining values v1...vn added to the suppressed exception list of v. 


¢ If the initialization of all resources completes normally, and the try block 
completes abruptly because of a throw of a value v, then: 


— If the automatic closings of all initialized resources complete normally, then 
the try-with-resources statement completes abruptly because of a throw of 
the value v. 


— Ifthe automatic closings of one or more initialized resources complete abruptly 
because of throws of values vi...vn, then the try-with-resources statement 
completes abruptly because of a throw of the value v with any remaining 
values V1...vn added to the suppressed exception list of v. 


¢ If the initialization of every resource completes normally, and the try block 
completes normally, then: 


— If one automatic closing of an initialized resource completes abruptly because 
of a throw of value v, and all other automatic closings of initialized resources 
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complete normally, then the t ry-with-resources statement completes abruptly 
because of a throw of the value v. 


— If more than one automatic closing of an initialized resource completes 
abruptly because of throws of values vi...vn, then the try-with-resources 
statement completes abruptly because of a throw of the value viz with any 
remaining values v2...vn added to the suppressed exception list of v1 (where 
v1 is the exception from the rightmost resource failing to close and vn is the 
exception from the leftmost resource failing to close). 


14.20.3.2 Extended try-with-resources 


A try-with-resources statement with at least one catch clause and/or a finally 
clause is called an extended t ry-with-resources statement. 


The meaning of an extended t ry-with-resources statement: 


try ResourceSpecification 
Block 

[Catches] 

[Finally] 


is given by the following translation to a basic t ry-with-resources statement nested 
inside a try-catch OF try-finally Or try-catch-finally statement: 


try { 
try ResourceSpecification 
Block 


} 
[Catches] 
[Finally] 


The effect of the translation is to put the resource specification "inside" the try 
statement. This allows a catch clause of an extended t ry-with-resources statement 
to catch an exception due to the automatic initialization or closing of any resource. 


Furthermore, all resources will have been closed (or attempted to be closed) by 
the time the finally block is executed, in keeping with the intent of the finally 
keyword. 


14.21 Unreachable Statements 


It is a compile-time error if a statement cannot be executed because it is 
unreachable. 
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This section is devoted to a precise explanation of the word "reachable." The idea is that 
there must be some possible execution path from the beginning of the constructor, method, 
instance initializer, or static initializer that contains the statement to the statement itself. 
The analysis takes into account the structure of statements. Except for the special treatment 
of while, do, and for statements whose condition expression has the constant value t rue, 
the values of expressions are not taken into account in the flow analysis. 


For example, a Java compiler will accept the code: 


int n = 5; 
while (n > 7) k = 2; 


even though the value of n is known at compile time and in principle it can be known at 
compile time that the assignment to k can never be executed. 


The rules in this section define two technical terms: 

¢ whether a statement is reachable 

¢ whether a statement can complete normally 

The definitions here allow a statement to complete normally only if it is reachable. 


To shorten the description of the rules, the customary abbreviation "iff" is used to 
mean "if and only if." 


A reachable break statement exits a statement if, within the break target, either 
there are no try statements whose try blocks contain the break statement, or there 
are try statements whose try blocks contain the break statement and all finally 
clauses of those try statements can complete normally. 


This definition is based on the logic around "attempts to transfer control" in §14.15. 


A continue statement continues a do statement if, within the do statement, either 
there are no try statements whose try blocks contain the continue statement, or 
there are try statements whose try blocks contain the continue statement and all 
finally clauses of those try statements can complete normally. 


The rules are as follows: 


¢ The block that is the body of a constructor, method, instance initializer, or static 
initializer is reachable. 


¢ An empty block that is not a switch block can complete normally iff it is 
reachable. 
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A non-empty block that is not a switch block can complete normally iff the last 
statement in it can complete normally. 


The first statement in a non-empty block that is not a switch block is reachable 
iff the block is reachable. 


Every other statement s in a non-empty block that is not a switch block is 
reachable iff the statement preceding s can complete normally. 


¢ A local class declaration statement can complete normally iff it is reachable. 
¢ A local variable declaration statement can complete normally iff it is reachable. 
e An empty statement can complete normally iff it is reachable. 
¢ A labeled statement can complete normally if at least one of the following is true: 
— The contained statement can complete normally. 
— There is a reachable break statement that exits the labeled statement. 
The contained statement is reachable iff the labeled statement is reachable. 
e An expression statement can complete normally iff it is reachable. 
e An if-then statement can complete normally iff it is reachable. 
The then-statement is reachable iff the if-then statement is reachable. 


An if-then-else statement can complete normally iff the then-statement can 
complete normally or the else-statement can complete normally. 


The then-statement is reachable iff the if-then-else statement is reachable. 


The else-statement is reachable iff the if-then-else statement is reachable. 


This handling of an if statement, whether or not it has an else part, is rather unusual. 
The rationale is given at the end of this section. 


¢ An assert statement can complete normally iff it is reachable. 


¢ A switch statement can complete normally iff at least one of the following is 
true: 


— The switch block is empty or contains only switch labels. 

— The last statement in the switch block can complete normally. 

— There is at least one switch label after the last switch block statement group. 
— The switch block does not contain a default label. 


— There is a reachable break statement that exits the switch statement. 
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¢ A switch block is reachable iff its switch statement is reachable. 


e A statement in a switch block is reachable iff its switch statement is reachable 
and at least one of the following is true: 


— It bears a case or default label. 


— There is a statement preceding it in the switch block and that preceding 
statement can complete normally. 


¢ A while statement can complete normally iff at least one of the following is true: 


— The while statement is reachable and the condition expression is not a constant 
expression (§15.28) with value true. 


— There is a reachable break statement that exits the while statement. 


The contained statement is reachable iff the while statement is reachable and the 
condition expression is not a constant expression whose value is false. 


¢ A do statement can complete normally iff at least one of the following is true: 


— The contained statement can complete normally and the condition expression 
is not a constant expression (§15.28) with value true. 


— The do statement contains a reachable continue statement with no label, and 
the do statement is the innermost while, do, or for statement that contains that 
continue statement, and the continue statement continues that do statement, 
and the condition expression is not a constant expression with value true. 


— The do statement contains a reachable continue statement with a label 1, and 
the do statement has label t, and the continue statement continues that do 
statement, and the condition expression is not a constant expression with value 


true. 
— There is a reachable break statement that exits the do statement. 
The contained statement is reachable iff the do statement is reachable. 


¢ A basic for statement can complete normally iff at least one of the following 
is true: 


— The for statement is reachable, there is a condition expression, and the 
condition expression is not a constant expression ($15.28) with value true. 


— There is a reachable break statement that exits the for statement. 


The contained statement is reachable iff the for statement is reachable and the 
condition expression is not a constant expression whose value is false. 
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¢ Anenhanced for statement can complete normally iff it is reachable. 
¢ A break, continue, return, Of throw statement cannot complete normally. 


¢ A synchronized statement can complete normally iff the contained statement 
can complete normally. 


The contained statement is reachable iff the synchronized statement is 
reachable. 


¢ Atry statement can complete normally iff both of the following are true: 


— The try block can complete normally or any catch block can complete 
normally. 


— Ifthe try statement has a finally block, then the finally block can complete 
normally. 


e The try block is reachable iff the try statement is reachable. 


¢ A catch block cis reachable iff both of the following are true: 


— Either the type of c’s parameter is an unchecked exception type or Exception 
or a superclass of Except ion, or some expression or throw Statement in the try 
block is reachable and can throw a checked exception whose type is assignable 
to the type of c's parameter. (An expression is reachable iff the innermost 
statement containing it is reachable.) 


See §15.6 for normal and abrupt completion of expressions. 


— There is no earlier catch block ain the try statement such that the type of c's 
parameter is the same as or a subclass of the type of a's parameter. 


¢ The Block of a catch block is reachable iff the catch block is reachable. 


¢ Ifa finally block is present, it is reachable iff the try statement is reachable. 
One might expect the if statement to be handled in the following manner: 
e An if-then statement can complete normally iff at least one of the following is true: 


— The if-then statement is reachable and the condition expression is not a 
constant expression whose value is true. 

— The then-statement can complete normally. 

The then-statement is reachable iff the if-then statement is reachable and the 

condition expression is not a constant expression whose value is false. 


e An if-then-else statement can complete normally iff the then-statement can 
complete normally or the else-statement can complete normally. 
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The then-statement is reachable iff the if-then-else statement is reachable and 
the condition expression is not a constant expression whose value is false. 


The else-statement is reachable iff the if-then-else statement is reachable and 
the condition expression is not a constant expression whose value is t rue. 


This approach would be consistent with the treatment of other control structures. However, 
in order to allow the if statement to be used conveniently for "conditional compilation" 
purposes, the actual rules differ. 


As an example, the following statement results in a compile-time error: 
while (false) { x=3; } 

because the statement x=3; is not reachable; but the superficially similar case: 
if (false) { x=3; } 


does not result in a compile-time error. An optimizing compiler may realize that the 
statement x=3; will never be executed and may choose to omit the code for that statement 
from the generated class file, but the statement x=3; is not regarded as "unreachable" in 
the technical sense specified here. 


The rationale for this differing treatment is to allow programmers to define "flag" variables 
such as: 


static final boolean DEBUG = false; 
and then write code such as: 
if (DEBUG) { x=3; } 


The idea is that it should be possible to change the value of DEBUG from false to true 
or from true to false and then compile the code correctly with no other changes to the 
program text. 


Conditional compilation comes with a caveat. If a set of classes that use a "flag" variable - 
or more precisely, any static constant variable (§4.12.4) - are compiled and conditional 
code is omitted, it does not suffice later to distribute just a new version of the class or 
interface that contains the definition of the flag. The classes that use the flag will not see 
its new value, so their behavior may be surprising. In essence, a change to the value of 
a flag is binary compatible with pre-existing binaries (no LinkageError occurs) but not 
behaviorally compatible. 


Another reason for "inlining" values of static constant variables is because of switch 
statements. They are the only kind of statement that relies on constant expressions, namely 
that each case label of a switch statement must be a constant expression whose value is 
different than every other case label. case labels are often references to static constant 
variables so it may not be immediately obvious that all the labels have different values. If it 
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is proven that there are no duplicate labels at compile time, then inlining the values into the 
class file ensures there are no duplicate labels at run time either - a very desirable property. 


Example 14.21-1. Conditional Compilation 


If the example: 


class Flags { static final boolean DEBUG = true; } 
class Test { 
public static void main(String[] args) { 
if (Flags .DEBUG) 
System.out.println("DEBUG is true"); 


is compiled and executed, it produces the output: 
DEBUG is true 
Suppose that a new version of class Flags is produced: 
class Flags { static final boolean DEBUG = false; } 


If Flags is recompiled but not Test, then running the new binary with the existing binary 
of Test produces the output: 


DEBUG is true 


because DEBUG is a static constant variable, so its value could have been used in 
compiling Test without making a reference to the class Flags. 


This behavior would also occur if Flags was an interface, as in the modified example: 


interface Flags { boolean DEBUG = true; } 
class Test { 
public static void main(String[] args) { 
if (Flags .DEBUG) 
System.out.println("DEBUG is true"); 


In fact, because the fields of interfaces are always static and final, we recommend 
that only constant expressions be assigned to fields of interfaces. We note, but do not 
recommend, that if a field of primitive type of an interface may change, its value may be 
expressed idiomatically as in: 


interface Flags { 
boolean debug = Boolean.valueOf (true) .booleanValue() ; 
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ensuring that this value is not a constant expression. Similar idioms exist for the other 
primitive types. 
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Expressions 


Mbucu of the work in a program is done by evaluating expressions, either for 
their side effects, such as assignments to variables, or for their values, which can 
be used as arguments or operands in larger expressions, or to affect the execution 
sequence in statements, or both. 


This chapter specifies the meanings of expressions and the rules for their 
evaluation. 


15.1 Evaluation, Denotation, and Result 


When an expression in a program is evaluated (executed), the result denotes one 
of three things: 


e A variable (§4.12) (in C, this would be called an lvalue) 
e A value (§4.2, §4.3) 
¢ Nothing (the expression is said to be void) 


If an expression denotes a variable, and a value is required for use in further 
evaluation, then the value of that variable is used. In this context, if the expression 
denotes a variable or a value, we may speak simply of the value of the expression. 


Value set conversion (§5.1.13) is applied to the result of every expression that 
produces a value, including when the value of a variable of type float or double 
is used. 


An expression denotes nothing if and only if it is a method invocation (§15.12) 
that invokes a method that does not return a value, that is, a method declared void 
($8.4). Such an expression can be used only as an expression statement (§14.8) or 
as the single expression of a lambda body (§15.27.2), because every other context 
in which an expression can appear requires the expression to denote something. An 
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expression statement or lambda body that is a method invocation may also invoke 
a method that produces a result; in this case the value returned by the method is 
quietly discarded. 


Evaluation of an expression can produce side effects, because expressions may 
contain embedded assignments, increment operators, decrement operators, and 
method invocations. 


An expression occurs in either: 


¢ The declaration of some (class or interface) type that is being declared: in a 
field initializer, in a static initializer, in an instance initializer, in a constructor 
declaration, in a method declaration, or in an annotation. 


e An annotation on a package declaration or on a top level type declaration. 


15.2 Forms of Expressions 


Expressions can be broadly categorized into one of the following syntactic forms: 
¢ Expression names (§6.5.6) 

e Primary expressions (§15.8 - $15.13) 

e Unary operator expressions ($15.14 - $15.16) 

¢ Binary operator expressions ($15.17 - §15.24, and $15.26) 

¢ Ternary operator expressions ($15.25) 

¢ Lambda expressions ($15.27) 


Precedence among operators is managed by a hierarchy of grammar productions. 
The lowest precedence operator is the arrow of a lambda expression (->), followed 
by the assignment operators. Thus, all expressions are syntactically included in the 
LambdaExpression and AssignmentExpression nonterminals: 


Expression: 
LambdaExpression 
AssignmentExpression 


When some expressions appear in certain contexts, they are considered poly 
expressions. The following forms of expressions may be poly expressions: 


¢ Parenthesized expressions (§15.8.5) 


EXPRESSIONS Type of an Expression 


¢ Class instance creation expressions ($15.9) 
¢ Method invocation expressions (§15.12) 

¢ Method reference expressions ($15.13) 

¢ Conditional expressions (§15.25) 

¢ Lambda expressions ($15.27) 


The rules determining whether an expression of one of these forms is a poly 
expression are given in the individual sections that specify these forms of 
expressions. 


Expressions that are not poly expressions are standalone expressions. Standalone 
expressions are expressions of the forms above when determined not to be poly 
expressions, as well as all expressions of all other forms. Expressions of all other 
forms are said to have a standalone form. 


Some expressions have a value that can be determined at compile time. These are 
constant expressions (§15.28). 


15.3 Type of an Expression 


If an expression denotes a variable or a value, then the expression has a type known 
at compile time. The type of a standalone expression can be determined entirely 
from the contents of the expression; in contrast, the type of a poly expression may 
be influenced by the expression's target type (§5 (Conversions and Contexts)). The 
rules for determining the type of an expression are explained separately below for 
each kind of expression. 


The value of an expression is assignment compatible (§5.2) with the type of the 
expression, unless heap pollution occurs (§4.12.2). 


Likewise, the value stored in a variable is always compatible with the type of the 
variable, unless heap pollution occurs. 


In other words, the value of an expression whose type is T is always suitable for 
assignment to a variable of type T. 


Note that an expression whose type is a class type F that is declared final is 
guaranteed to have a value that is either a null reference or an object whose class 
is F itself, because final types have no subclasses. 
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15.4 FP-strict Expressions 


If the type of an expression is float or double, then there is a question as to what 
value set (§4.2.3) the value of the expression is drawn from. This is governed by 
the rules of value set conversion (§5.1.13); these rules in turn depend on whether 
or not the expression is FP-strict. 


Every constant expression (§15.28) is FP-strict. 


If an expression is not a constant expression, then consider all the class declarations, 
interface declarations, and method declarations that contain the expression. If any 
such declaration bears the strictfp modifier (§8.1.1.3, $8.4.3.5, §9.1.1.2), then 
the expression is FP-strict. 


If a class, interface, or method, x, is declared strictfp, then x and any class, 
interface, method, constructor, instance initializer, static initializer, or variable 
initializer within x is said to be FP-strict. 


Note that an annotation's element value (§9.7) is always FP-strict, because it is always a 
constant expression. 


It follows that an expression is not FP-strict if and only if it is not a constant 
expression and it does not appear within any declaration that has the strictfp 
modifier. 


Within an FP-strict expression, all intermediate values must be elements of the 
float value set or the double value set, implying that the results of all FP- 
strict expressions must be those predicted by IEEE 754 arithmetic on operands 
represented using single and double formats. 


Within an expression that is not FP-strict, some leeway is granted for an 
implementation to use an extended exponent range to represent intermediate 
results; the net effect, roughly speaking, is that a calculation might produce "the 
correct answer" in situations where exclusive use of the float value set or double 
value set might result in overflow or underflow. 


15.5 Expressions and Run-Time Checks 


If the type of an expression is a primitive type, then the value of the expression is 
of that same primitive type. 


EXPRESSIONS Expressions and Run-Time Checks 


If the type of an expression is a reference type, then the class of the referenced 
object, or even whether the value is a reference to an object rather than nu11, is not 
necessarily known at compile time. There are a few places in the Java programming 
language where the actual class of a referenced object affects program execution 
in a manner that cannot be deduced from the type of the expression. They are as 
follows: 


¢ Method invocation (§15.12). The particular method used for an invocation 
o.m(...) iS chosen based on the methods that are part of the class or interface 
that is the type of o. For instance methods, the class of the object referenced by 
the run-time value of o participates because a subclass may override a specific 
method already declared in a parent class so that this overriding method is 
invoked. (The overriding method may or may not choose to further invoke the 
original overridden m method.) 


e The instanceof operator ($15.20.2). An expression whose type is a reference 
type may be tested using instanceof to find out whether the class of the object 
referenced by the run-time value of the expression may be converted to some 
other reference type. 


¢ Casting ($15.16). The class of the object referenced by the run-time value of the 
operand expression might not be compatible with the type specified by the cast 
operator. For reference types, this may require a run-time check that throws an 
exception if the class of the referenced object, as determined at run time, cannot 
be converted to the target type. 


¢ Assignment to an array component of reference type ($10.5, §15.13, §15.26.1). 
The type-checking rules allow the array type s[] to be treated as a subtype of 
T[] if sis a subtype of r, but this requires a run-time check for assignment to an 
array component, similar to the check performed for a cast. 


¢ Exception handling (§14.20). An exception is caught by a catch clause only if 
the class of the thrown exception object is an instanceof the type of the formal 
parameter of the catch clause. 


Situations where the class of an object is not statically known may lead to run-time 
type errors. 


In addition, there are situations where the statically known type may not be accurate 
at run time. Such situations can arise in a program that gives rise to compile-time 
unchecked warnings. Such warnings are given in response to operations that cannot 
be statically guaranteed to be safe, and cannot immediately be subjected to dynamic 
checking because they involve non-reifiable types ($4.7). As a result, dynamic 
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checks later in the course of program execution may detect inconsistencies and 
result in run-time type errors. 


A run-time type error can occur only in these situations: 


¢ In a cast, when the actual class of the object referenced by the value of the 
operand expression is not compatible with the target type specified by the cast 
operator (§5.5, $15.16); in this case a ClassCastException is thrown. 


¢ In an automatically generated cast introduced to ensure the validity of an 
operation on a non-reifiable type (§4.7). 


¢ In an assignment to an array component of reference type, when the actual class 
of the object referenced by the value to be assigned is not compatible with the 
actual run-time component type of the array ($10.5, $15.13, §15.26.1); in this 
case an ArrayStoreException Is thrown. 


e When an exception is not caught by any catch clause of a try statement 
($14.20); in this case the thread of control that encountered the exception first 
attempts to invoke an uncaught exception handler ($11.3) and then terminates. 


15.6 Normal and Abrupt Completion of Evaluation 


Every expression has a normal mode of evaluation in which certain computational 
steps are carried out. The following sections describe the normal mode of 
evaluation for each kind of expression. 


If all the steps are carried out without an exception being thrown, the expression 
is said to complete normally. 


If, however, evaluation of an expression throws an exception, then the expression is 
said to complete abruptly. An abrupt completion always has an associated reason, 
which is always a throw with a given value. 


Run-time exceptions are thrown by the predefined operators as follows: 


e A class instance creation expression (§15.9.4), array creation expression 
(§15.10.2), method reference expression (§15.13.3), array initializer expression 
($10.6), string concatenation operator expression (§15.18.1), or lambda 
expression (§15.27.4) throws an OutOfMemoryError if there is insufficient 
memory available. 


EXPRESSIONS Normal and Abrupt Completion of Evaluation 


e An array creation expression ($15.10.2) throws a 
Negat iveArraySizeException if the value of any dimension expression is less 
than zero. 


e An array access expression (§15.10.4) throws a NullPointerException if the 
value of the array reference expression is null. 


e An array access expression (§$15.10.4) throws an 
ArrayIndexOutOfBoundsException if the value of the array index expression 
is negative or greater than or equal to the Length of the array. 


¢ A field access expression ($15.11) throws a Nul1lPointerExcept ion if the value 
of the object reference expression is null. 


¢ A method invocation expression (§15.12) that invokes an instance method 
throws a NullPointerException if the target reference is null. 


¢ A cast expression (§15.16) throws a ClassCastException if a cast is found to 
be impermissible at run time. 


¢ An integer division (§15.17.2) or integer remainder (§15.17.3) operator throws 
an ArithmeticException if the value of the right-hand operand expression is 
zero. 


e An assignment to an array component of reference type ($15.26.1), a method 
invocation expression (§15.12), or a prefix or postfix increment (§15.14.2, 
§15.15.1) or decrement operator (§15.14.3, §15.15.2) may all throw an 
OutOfMemoryError as a result of boxing conversion (§5.1.7). 


e An assignment to an array component of reference type (§15.26.1) throws an 
ArrayStoreException when the value to be assigned is not compatible with the 
component type of the array ($10.5). 


A method invocation expression can also result in an exception being thrown if an 
exception occurs that causes execution of the method body to complete abruptly. 


A class instance creation expression can also result in an exception being thrown if 
an exception occurs that causes execution of the constructor to complete abruptly. 


Various linkage and virtual machine errors may also occur during the evaluation 
of an expression. By their nature, such errors are difficult to predict and difficult 
to handle. 


If an exception occurs, then evaluation of one or more expressions may be 
terminated before all steps of their normal mode of evaluation are complete; such 
expressions are said to complete abruptly. 
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If evaluation of an expression requires evaluation of a subexpression, then abrupt 
completion of the subexpression always causes the immediate abrupt completion 
of the expression itself, with the same reason, and all succeeding steps in the normal 
mode of evaluation are not performed. 


The terms "complete normally" and "complete abruptly" are also applied to the 
execution of statements ($14.1). A statement may complete abruptly for a variety 
of reasons, not just because an exception is thrown. 


15.7. Evaluation Order 


The Java programming language guarantees that the operands of operators appear 
to be evaluated in a specific evaluation order, namely, from left to right. 


It is recommended that code not rely crucially on this specification. Code is usually clearer 
when each expression contains at most one side effect, as its outermost operation, and when 
code does not depend on exactly which exception arises as a consequence of the left-to- 
right evaluation of expressions. 


15.7.1 Evaluate Left-Hand Operand First 


The left-hand operand of a binary operator appears to be fully evaluated before any 
part of the right-hand operand is evaluated. 


If the operator is a compound-assignment operator (§15.26.2), then evaluation of 
the left-hand operand includes both remembering the variable that the left-hand 
operand denotes and fetching and saving that variable's value for use in the implied 
binary operation. 


If evaluation of the left-hand operand of a binary operator completes abruptly, no 
part of the right-hand operand appears to have been evaluated. 


Example 15.7.1-1. Left-Hand Operand Is Evaluated First 


In the following program, the * operator has a left-hand operand that contains an assignment 
to a variable and a right-hand operand that contains a reference to the same variable. The 
value produced by the reference will reflect the fact that the assignment occurred first. 


class Testl { 
public static void main(String[] args) { 
int i = 2; 
int j = (i=3) * i; 
System.out.printin(j); 


EXPRESSIONS Evaluation Order 


This program produces the output: 


It is not permitted for evaluation of the * operator to produce 6 instead of 9. 
Example 15.7.1-2. Implicit Left-Hand Operand In Operator Of Compound Assigment 


In the following program, the two assignment statements both fetch and remember the value 
of the left-hand operand, which is 9, before the right-hand operand of the addition operator 
is evaluated, at which point the variable is set to 3. 


class Test2 { 
public static void main(String[] args) { 


int a = 9; 

a+= (a = 3); // first example 
System.out.printin(a); 

int b = 9; 


b=b + (b = 3); =// second example 
System.out.printin(b); 


This program produces the output: 


12 
12 


It is not permitted for either assignment (compound for a, simple for b) to produce the 
result 6. 


See also the example in §15.26.2. 


Example 15.7.1-3. Abrupt Completion of Evaluation of the Left-Hand Operand 


class Test3 { 
public static void main(String[] args) { 

int j = 1; 

try { 
int i = forgetIt() / (j = 2); 

} catch (Exception e) { 
System.out.printin(e); 
System.out.println("Now j = " + 4); 

} 

} 
static int forgetIt() throws Exception { 
throw new Exception("I'm outta here!"); 


} 
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This program produces the output: 


java.lang.Exception: I'm outta here! 
Now j = 1 


That is, the left-hand operand forget It () of the operator / throws an exception before 
the right-hand operand is evaluated and its embedded assignment of 2 to j occurs. 


15.7.2 Evaluate Operands before Operation 


The Java programming language guarantees that every operand of an operator 
(except the conditional operators «&, ||, and ? :) appears to be fully evaluated 
before any part of the operation itself is performed. 


If the binary operator is an integer division / (§15.17.2) or integer remainder 
% (§15.17.3), then its execution may raise an ArithmeticException, but this 
exception is thrown only after both operands of the binary operator have been 
evaluated and only if these evaluations completed normally. 


Example 15.7.2-1. Evaluation of Operands Before Operation 


class Test { 
public static void main(String[] args) { 
int divisor = 0; 
try { 
int i=1/ (divisor * loseBig()); 
} catch (Exception e) { 
System.out.printin(e); 
} 
} 


static int loseBig() throws Exception { 
throw new Exception("Shuffle off to Buffalo!"); 


} 
This program produces the output: 
java.lang.Exception: Shuffle off to Buffalo! 
and not: 
java.lang.ArithmeticException: / by zero 


since no part of the division operation, including signaling of a divide-by-zero exception, 
may appear to occur before the invocation of loseBig completes, even though the 
implementation may be able to detect or infer that the division operation would certainly 
result in a divide-by-zero exception. 
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15.7.3 Evaluation Respects Parentheses and Precedence 


The Java programming language respects the order of evaluation indicated 
explicitly by parentheses and implicitly by operator precedence. 


An implementation of the Java programming language may not take advantage of algebraic 
identities such as the associative law to rewrite expressions into a more convenient 
computational order unless it can be proven that the replacement expression is equivalent 
in value and in its observable side effects, even in the presence of multiple threads of 
execution (using the thread execution model in §17 (Threads and Locks)), for all possible 
computational values that might be involved. 


In the case of floating-point calculations, this rule applies also for infinity and not- 
a-number (NaN) values. 


For example, ! (x<y) may not be rewritten as x>=y, because these expressions have 
different values if either x or y is NaN or both are NaN. 


Specifically, floating-point calculations that appear to be mathematically 
associative are unlikely to be computationally associative. Such computations must 
not be naively reordered. 


For example, it is not correct for a Java compiler to rewrite 4.0*x*0.5 as 2.0*x; while 
roundoff happens not to be an issue here, there are large values of x for which the first 
expression produces infinity (because of overflow) but the second expression produces a 
finite result. 


So, for example, the test program: 


strictfp class Test { 
public static void main(String[] args) { 
double d = 8e+307; 
System.out.printin(4.0 * d * 0.5); 
System.out.println(2.0 * d); 


prints: 


Infinity 
1.6e+308 


because the first expression overflows and the second does not. 


In contrast, integer addition and multiplication are provably associative in the Java 
programming language. 
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For example a+b+c, where a, b, and c are local variables (this simplifying assumption 
avoids issues involving multiple threads and volatile variables), will always produce 
the same answer whether evaluated as (a+b) +c or a+ (b+c); if the expression b+c occurs 
nearby in the code, a smart Java compiler may be able to use this common subexpression. 


15.7.4 Argument Lists are Evaluated Left-to-Right 


In a method or constructor invocation or class instance creation expression, 
argument expressions may appear within the parentheses, separated by commas. 
Each argument expression appears to be fully evaluated before any part of any 
argument expression to its right. 


If evaluation of an argument expression completes abruptly, no part of any 
argument expression to its right appears to have been evaluated. 


Example 15.7.4-1. Evaluation Order At Method Invocation 


class Testl1 { 
public static void main(String[] args) { 
String s = "going, "; 
print3(s, s, s = "gone"); 
} 
static void print3(String a, String b, String c) { 


System.out.println(a + b +c); 


This program produces the output: 
going, going, gone 


because the assignment of the string "gone" to s occurs after the first two arguments to 
print3 have been evaluated. 


Example 15.7.4-2. Abrupt Completion of Argument Expression 


class Test2 { 
static int id; 
public static void main(String[] args) { 
try { 
test(id = 1, oops(), id = 3); 
} catch (Exception e) { 
System.out.println(e + ", id=" + id); 


} 
static int test(int a, int b, int c) { 
return a+ b+ oc; 


} 
static int oops() throws Exception { 
throw new Exception ("oops") ; 
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} 
This program produces the output: 
java.lang.Exception: oops, id=1 


because the assignment of 3 to id is not executed. 


15.7.5 Evaluation Order for Other Expressions 


The order of evaluation for some expressions is not completely covered by these 
general rules, because these expressions may raise exceptional conditions at times 
that must be specified. See the detailed explanations of evaluation order for the 
following kinds of expressions: 


¢ class instance creation expressions (§15.9.4) 

* array creation expressions (§15.10.2) 

* array access expressions (§15.10.4) 

¢ method invocation expressions (§15.12.4) 

¢ method reference expressions (§15.13.3) 

* assignments involving array components ($15.26) 


¢ lambda expressions (§15.27.4) 


15.8 Primary Expressions 


Primary expressions include most of the simplest kinds of expressions, from 
which all others are constructed: literals, object creations, field accesses, method 
invocations, method references, and array accesses. A parenthesized expression is 
also treated syntactically as a primary expression. 


Primary: 


PrimaryNoNewArray 
ArrayCreationExpression 
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PrimaryNoNewArray: 
Literal 
ClassLiteral 
this 
TypeName . this 

( Expression ) 
ClassInstanceCreationExpression 
FieldAccess 

ArrayAccess 

MethodInvocation 
MethodReference 


This part of the grammar of the Java programming language is unusual, in two ways. First, 
one might expect simple names, such as names of local variables and method parameters, 
to be primary expressions. For technical reasons, names are grouped together with primary 
expressions a little later when postfix expressions are introduced (§ 15.14). 


The technical reasons have to do with allowing left-to-right parsing of Java programs with 
only one-token lookahead. Consider the expressions (z[3]) and (z[]). The first is a 
parenthesized array access (§15.10.3) and the second is the start of a cast (§15.16). At 
the point that the look-ahead symbol is [, a left-to-right parse will have reduced the z 
to the nonterminal Name. In the context of a cast we prefer not to have to reduce the 
name to a Primary, but if Name were one of the alternatives for Primary, then we could 
not tell whether to do the reduction (that is, we could not determine whether the current 
situation would turn out to be a parenthesized array access or a cast) without looking 
ahead two tokens, to the token following the [. The grammar presented here avoids the 
problem by keeping Name and Primary separate and allowing either in certain other syntax 
tules (those for ClassInstanceCreationExpression, MethodInvocation, ArrayAccess, and 
PostfixExpression, though not FieldAccess because it uses an identifier directly). This 
strategy effectively defers the question of whether a Name should be treated as a Primary 
until more context can be examined. 


The second unusual feature avoids a potential grammatical ambiguity in the expression 
"new int[3][3]" which in Java always means a single creation of a multidimensional 
array, but which, without appropriate grammatical finesse, might also be interpreted as 
meaning the same as "(new int [3]) [3]". 


This ambiguity is eliminated by splitting the expected definition of Primary into Primary 
and PrimaryNoNewArray. (This may be compared to the splitting of Statement into 
Statement and StatementNoShortlf (§14.5) to avoid the "dangling else" problem.) 


15.8.1 Lexical Literals 


A literal ($3.10) denotes a fixed, unchanging value. 


The following production from §3.10 is shown here for convenience: 
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Literal: 
IntegerLiteral 
FloatingPointLiteral 
BooleanLiteral 
CharacterLiteral 
StringLiteral 
NullLiteral 


The type of a literal is determined as follows: 
¢ The type of an integer literal (§3.10.1) that ends with & or 1 is long (§4.2.1). 
The type of any other integer literal is int (§4.2.1). 


¢ The type of a floating-point literal (§3.10.2) that ends with F or £ is float and 
its value must be an element of the float value set (§4.2.3). 


The type of any other floating-point literal is double and its value must be an 
element of the double value set (§4.2.3). 


¢ The type of a boolean literal (§3.10.3) is boolean (§4.2.5). 
e The type of a character literal (§3.10.4) is char (§4.2.1). 
¢ The type of a string literal ($3.10.5) is string (§4.3.3). 


¢ The type of the null literal nu11 (§3.10.7) is the null type ($4.1); its value is the 
null reference. 


Evaluation of a lexical literal always completes normally. 


15.8.2 Class Literals 


A class literal is an expression consisting of the name of a class, interface, array, 
or primitive type, or the pseudo-type void, followed by a'.' and the token class. 


ClassLiteral: 
TypeName {{ 1} . class 
NumericType {{ 1} . class 
boolean {t i} . class 


void . class 


The TypeName must denote a class or interface type that is accessible (§6.6). It is 
a compile-time error if the TypeName denotes a class or interface type that is not 
accessible, or denotes a type variable. 


The type of c.class, where cis the name of a class, interface, or array type ($4.3), 
iS Class<c>. 
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The type of p.class, where p is the name of a primitive type (§4.2), is Class<B>, 
where B is the type of an expression of type p after boxing conversion (§5.1.7). 


The type of void.class (§8.4.5) is Class<Void>. 


A class literal evaluates to the class object for the named type (or for void) as 
defined by the defining class loader ($12.2) of the class of the current instance. 


15.8.3 this 


The keyword this may be used only in the following contexts: 

¢ in the body of an instance method or default method (§8.4.7, §9.4.3) 
¢ in the body of a constructor of a class (§8.8.7) 

* in an instance initializer of a class (§8.6) 

¢ in the initializer of an instance variable of a class (§8.3.2) 

* to denote a receiver parameter (§8.4) 

If it appears anywhere else, a compile-time error occurs. 


The keyword this may be used in a lambda expression only if it is allowed in the 
context in which the lambda expression appears. Otherwise, a compile-time error 
occurs. 


When used as a primary expression, the keyword this denotes a value that is 
a reference to the object for which the instance method or default method was 
invoked ($15.12), or to the object being constructed. The value denoted by this in 
a lambda body is the same as the value denoted by this in the surrounding context. 


The keyword this is also used in explicit constructor invocation statements (§8.8.7.1). 


The type of this is the class or interface type r within which the keyword this 
occurs. 


Default methods provide the unique ability to access this inside an interface. (All other 
interface methods are either abstract or static, so provide no access to this.) As a 
result, it is possible for this to have an interface type. 


At run time, the class of the actual object referred to may be 1, if Tis a class type, 
or a class that is a subtype of T. 


Example 15.8.3-1. The this Expression 


class IntVector { 
int[] v; 
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boolean equals(IntVector other) { 


if (this == other) 
return true; 
if (v.length != other.v.length) 
return false; 
for (int i = 0; i < v.length; i++) { 
if (v[i] != other.v[i]) return false; 


} 


return true; 


Here, the class Int Vector implements a method equals, which compares two vectors. 
If the other vector is the same vector object as the one for which the equals method was 
invoked, then the check can skip the length and value comparisons. The equals method 
implements this check by comparing the reference to the other object to this. 


15.8.4 Qualified this 


Any lexically enclosing instance (§8.1.3) can be referred to by explicitly qualifying 
the keyword this. 


Let r be the type denoted by TypeName. Let n be an integer such that ris the n'th 
lexically enclosing type declaration of the class or interface in which the qualified 
this expression appears. 


The value of an expression of the form TypeName.this is the n'th lexically 
enclosing instance of this. 


The type of the expression is T. 


It is a compile-time error if the expression occurs in a class or interface which is 
not an inner class of class r or T itself. 


15.8.5 Parenthesized Expressions 


A parenthesized expression is a primary expression whose type is the type of the 
contained expression and whose value at run time is the value of the contained 
expression. If the contained expression denotes a variable then the parenthesized 
expression also denotes that variable. 


The use of parentheses affects only the order of evaluation, except for a corner 
case whereby (-2147483648) and (-9223372036854775808L) are legal but - 
(2147483648) and - (9223372036854775808L) are illegal. 


This is because the decimal literals 2147483648 and 9223372036854775808L are 
allowed only as an operand of the unary minus operator (§3.10.1). 


15.8 


503 


15.9 


504 


Class Instance Creation Expressions EXPRESSIONS 


In particular, the presence or absence of parentheses around an expression does not 
(except for the case noted above) affect in any way: 


¢ the choice of value set (§4.2.3) for the value of an expression of type float or 
double. 


¢ whether a variable is definitely assigned, definitely assigned when true, 
definitely assigned when false, definitely unassigned, definitely unassigned 
when true, or definitely unassigned when false (§16 (Definite Assignment)). 


If a parenthesized expression appears in a context of a particular kind with target 
type T(§5 (Conversions and Contexts)), its contained expression similarly appears 
in acontext of the same kind with target type r. 


If the contained expression is a poly expression ($15.2), the parenthesized 
expression is also a poly expression. Otherwise, it is a standalone expression. 


A poly parenthesized expression is compatible with a target type rif its contained 
expression is compatible with r. 


15.9 Class Instance Creation Expressions 


A class instance creation expression is used to create new objects that are instances 
of classes. 


ClassInstanceCreationExpression: 
UnqualifiedClassInstanceCreationExpression 
ExpressionName . UnqualifiedClassInstanceCreationExpression 
Primary . UnqualifiedClassInstanceCreationExpression 


UnqualifiedClassInstanceCreationExpression: 
new [TypeArguments ] 
ClassOrInterfaceTypeToInstantiate ( [ArgumentList] ) [ClassBody] 


ClassOrInterfaceTypeToInstantiate: 
{Annotation} Identifier { . {Annotation} Identifier} 
[TypeArgumentsOrDiamond] 


TypeArgumentsOrDiamond: 
TypeArguments 


<> 


The following production from §15.12 is shown here for convenience: 
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ArgumentList: 
Expression {, Expression} 


A class instance creation expression specifies a class to be instantiated, possibly 
followed by type arguments (§4.5.1) or a diamond (<>) if the class being 
instantiated is generic ($8.1.2), followed by (a possibly empty) list of actual value 
arguments to the constructor. 


If the type argument list to the class is empty — the diamond form <> — the type 
arguments of the class are inferred. It is legal, though strongly discouraged as a 


matter of style, to have white space between the "<" and ">" of a diamond. 


If the constructor is generic (§8.8.4), the type arguments to the constructor may 
similarly either be inferred or passed explicitly. If passed explicitly, the type 
arguments to the constructor immediately follow the keyword new. 


It is a compile-time error if a class instance creation expression provides type 
arguments to a constructor but uses the diamond form for type arguments to the 
class. 


This rule is introduced because inference of a generic class's type arguments may influence 
the constraints on a generic constructor's type arguments. 


If TypeArguments is present immediately after new, or immediately before (, then 
it is a compile-time error if any of the type arguments are wildcards (§4.5.1). 


The exception types that a class instance creation expression can throw are 
specified in §11.2.1. 


Class instance creation expressions have two forms: 
¢ Unqualified class instance creation expressions begin with the keyword new. 


An unqualified class instance creation expression may be used to create an 
instance of a class, regardless of whether the class is a top level ($7.6), member 
(§8.5, §9.5), local ($14.3), or anonymous class (§15.9.5). 


¢ Qualified class instance creation expressions begin with a Primary expression 
or an ExpressionName. 


A qualified class instance creation expression enables the creation of instances 
of inner member classes and their anonymous subclasses. 


Both unqualified and qualified class instance creation expressions may optionally 
end with a class body. Such a class instance creation expression declares an 
anonymous Class (§15.9.5) and creates an instance of it. 
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A class instance creation expression is a poly expression (§15.2) if it uses the 
diamond form for type arguments to the class, and it appears in an assignment 
context or an invocation context (§5.2, §5.3). Otherwise, it is a standalone 
expression. 


We say that a class is instantiated when an instance of the class is created by a class 
instance creation expression. Class instantiation involves determining the class 
to be instantiated (§15.9.1), the enclosing instances (if any) of the newly created 
instance (§15.9.2), and the constructor to be invoked to create the new instance 
($15.9.3). 


15.9.1 Determining the Class being Instantiated 


If ClassOrInterfaceTypeToInstantiate ends with TypeArguments (rather than <>), 
then ClassOrInterfaceTypeToInstantiate must denote a well-formed parameterized 
type ($4.5), or a compile-time error occurs. 


If ClassOrInterfaceTypeToInstantiate ends with <>, but the type denoted by the 
Identifier in ClassOrInterfaceTypeToInstantiate is not generic, then a compile-time 
error occurs. 


If the class instance creation expression ends in a class body, then the class being 
instantiated is an anonymous class. Then: 


¢ If the class instance creation expression is unqualified, then: 


The Identifier in ClassOrInterfaceTypeToInstantiate must denote either a class 
that is accessible, non-final, and not an enum type, or an interface that is 
accessible ($6.6). Otherwise a compile-time error occurs. 


If the Identifier in ClassOrInterfaceTypeToInstantiate denotes a class, c, then an 
anonymous direct subclass of c is declared. If TypeArguments is present, then c 
has type arguments given by TypeArguments; if <> is present, then c will have its 
type arguments inferred in §15.9.3; otherwise, chas no type arguments. The body 
of the subclass is the ClassBody given in the class instance creation expression. 
The class being instantiated is the anonymous subclass. 


If the Identifier in ClassOrInterfaceTypeToInstantiate denotes an interface, 1, 
then an anonymous direct subclass of Object that implements r is declared. If 
TypeArguments is present, then r has type arguments given by TypeArguments; 
if <> is present, then r will have its type arguments inferred in § 15.9.3; otherwise, 
Thas no type arguments. The body of the subclass is the ClassBody given in the 
class instance creation expression. The class being instantiated is the anonymous 
subclass. 


EXPRESSIONS Class Instance Creation Expressions 


¢ If the class instance creation expression is qualified, then: 


The Identifier in ClassOrInterfaceTypeToInstantiate must unambiguously 
denote an inner class that is accessible, non-final, not an enum type, 
and a member of the compile-time type of the Primary expression or the 
ExpressionName. Otherwise, a compile-time error occurs. 


Let the Identifier in ClassOrInterfaceTypeToInstantiate denote a class, c. An 
anonymous direct subclass of c is declared. If TypeArguments is present, then c 
has type arguments given by TypeArguments; if <> is present, then c will have its 
type arguments inferred in §15.9.3; otherwise, chas no type arguments. The body 
of the subclass is the ClassBody given in the class instance creation expression. 
The class being instantiated is the anonymous subclass. 


If a class instance creation expression does not declare an anonymous class, then: 
¢ If the class instance creation expression is unqualified, then: 


The Identifier in ClassOrInterfaceTypeToInstantiate must denote a class that 
is accessible, non-abstract, and not an enum type. Otherwise, a compile-time 
error occurs. 


The class being instantiated is specified by the Jdentifier in 
ClassOrInterfaceTypeToInstantiate. If TypeArguments is present, then the class 
has type arguments given by TypeArguments; if <> is present, then the class will 
have its type arguments inferred in §15.9.3; otherwise, the class has no type 
arguments. 


¢ If the class instance creation expression is qualified, then: 


The ClassOrInterfaceTypeTolnstantiate must unambiguously denote an inner 
class that is accessible, non-abstract, not an enum type, and a member of the 
compile-time type of the Primary expression or the ExpressionName. 


The class being instantiated is specified by the Jdentifier in 
ClassOrInterfaceTypeToInstantiate. If TypeArguments is present, then the class 
has type arguments given by TypeArguments; if <> is present, then the class will 
have its type arguments inferred in §15.9.3; otherwise, the class has no type 
arguments. 


15.9.2 Determining Enclosing Instances 


Let c be the class being instantiated, and let i be the instance being created. If 
c is an inner class, then i may have an immediately enclosing instance (§8.1.3), 
determined as follows: 


15.9 


507 


15.9 Class Instance Creation Expressions EXPRESSIONS 


¢ If cis an anonymous class, then: 


— If the class instance creation expression occurs in a static context, then i has 
no immediately enclosing instance. 


— Otherwise, the immediately enclosing instance of i is this. 
¢ If cis a local class, then: 
— If coccurs in a static context, then i has no immediately enclosing instance. 


— Otherwise, if the class instance creation expression occurs in a static context, 
then a compile-time error occurs. 


— Otherwise, let o be the immediately enclosing class of c. Let n be an integer 
such that ois the n'th lexically enclosing type declaration of the class in which 
the class instance creation expression appears. 


The immediately enclosing instance of i is the n'th lexically enclosing instance 
of this. 


e If cis an inner member class, then: 
— If the class instance creation expression is unqualified, then: 


>» If the class instance creation expression occurs in a static context, then a 
compile-time error occurs. 


>» Otherwise, if cis a member of a class enclosing the class in which the class 
instance creation expression appears, then let obe the immediately enclosing 
class of which c is a member. Let n be an integer such that o is the n'th 
lexically enclosing type declaration of the class in which the class instance 
creation expression appears. 


The immediately enclosing instance of i is the n'th lexically enclosing 
instance of this. 


» Otherwise, a compile-time error occurs. 


— If the class instance creation expression is qualified, then the immediately 
enclosing instance of i is the object that is the value of the Primary expression 
or the ExpressionName. 


If cis an anonymous class, and its direct superclass sis an inner class, then i may 
have an immediately enclosing instance with respect to s, determined as follows: 


¢ If sis a local class, then: 


— If s occurs in a static context, then i has no immediately enclosing instance 
with respect to s. 
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— Otherwise, if the class instance creation expression occurs in a static context, 
then a compile-time error occurs. 


— Otherwise, let o be the immediately enclosing type declaration of s. Let n be an 
integer such that o is the n'th lexically enclosing type declaration of the class 
in which the class instance creation expression appears. 


The immediately enclosing instance of i with respect to s is the n'th lexically 
enclosing instance of this. 


e If sis an inner member class, then: 
— If the class instance creation expression is unqualified, then: 


>» If the class instance creation expression occurs in a static context, then a 
compile-time error occurs. 


>» Otherwise, if sis a member of a class enclosing the class in which the class 
instance creation expression appears, then let obe the immediately enclosing 
class of which s is a member. Let n be an integer such that o is the n'th 
lexically enclosing type declaration of the class in which the class instance 
creation expression appears. 


The immediately enclosing instance of i with respect to sis the 'th lexically 
enclosing instance of this. 


» Otherwise, a compile-time error occurs. 


— If the class instance creation expression is qualified, then the immediately 
enclosing instance of i with respect to s is the object that is the value of the 
Primary expression or the ExpressionName. 


15.9.3 Choosing the Constructor and its Arguments 


Let c be the class being instantiated. To create an instance of c, i, a constructor of 
cis chosen at compile time by the following rules. 


First, the actual arguments to the constructor invocation are determined: 
¢ If cis an anonymous class with direct superclass s, then: 


— If sis not an inner class, or if sis a local class that occurs in a static context, 
then the arguments to the constructor are the arguments in the argument list 
of the class instance creation expression, if any, in the order they appear in 
the expression. 
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— Otherwise, the first argument to the constructor is the immediately enclosing 
instance of i with respect to s (§15.9.2), and the subsequent arguments to the 
constructor are the arguments in the argument list of the class instance creation 
expression, if any, in the order they appear in the class instance creation 
expression. 


¢ If cis a local class or a private inner member class, then the arguments to 
the constructor are the arguments in the argument list of the class instance 
creation expression, if any, in the order they appear in the class instance creation 
expression. 


¢ If c is a non-private inner member class, then the first argument to the 
constructor is the immediately enclosing instance of i (§8.8.1, §15.9.2), and the 
subsequent arguments to its constructor are the arguments in the argument list 
of the class instance creation expression, if any, in the order they appear in the 
class instance creation expression. 


¢ Otherwise, the arguments to the constructor are the arguments in the argument 
list of the class instance creation expression, if any, in the order they appear in 
the expression. 


Second, a constructor of c and corresponding throws clause and return type are 
determined: 


¢ If the class instance creation expression does not use <>, then: 
— If cis not an anonymous class, then: 


Let r be the type denoted by c followed by any class type arguments 
in the expression. The process specified in §15.12.2, modified to handle 
constructors, is used to choose one of the constructors of rT and determine its 
throws Clause. 


If there is no unique most-specific constructor in r that is both applicable and 
accessible ($6.6), then a compile-time error occurs (as in method invocations). 


Otherwise, the return type corresponding to the chosen constructor is T. 
— If cis an anonymous class, then: 


The process specified in §15.12.2, modified to handle constructors, is used to 
choose one of the constructors of the direct superclass of c and determine its 
throws Clause. 


If there is no unique most-specific constructor in the direct superclass of c 
that is both applicable and accessible, then a compile-time error occurs (as in 
method invocations). 


EXPRESSIONS Class Instance Creation Expressions 15.9 


Otherwise, c’s anonymous constructor is chosen as the constructor of c 
(§15.9.5.1). Its body consists of an explicit constructor invocation (§8.8.7.1) 
of the constructor chosen in the direct superclass of c. 


The throws clause of the chosen constructor includes the exceptions in the 
throws Clause of the constructor chosen in the direct superclass of c. 


The return type corresponding to the chosen constructor is the anonymous 
class type. 


¢ If the class instance creation expression uses <>, then: 


If cis not an anonymous class, let p be the same as c. If cis an anonymous class, 
let p be the superclass or superinterface of c named by the class instance creation 
expression. 


If pis a class, let c;...c, be the constructors of class p. If p is an interface, let 
C1...Cn be a singleton list (n = 1) containing the zero-argument constructor of 
class Object. 


A list of methods m;...m, is defined for the purpose of overload resolution and type 
argument inference. For all j (1 <j <n), m; is defined in terms of c, as follows: 


— A substitution 6, is first defined to instantiate the types in c3. 


Let F;...Fp be the type parameters of p, and let G;...G, be the type parameters 
(if any) of c;. Let x;...x, and y;...Y, be type variables with distinct names that 
are not in scope in the body of p. 


O,i8 [Fi:=X1, -.-, Fpt=Xpr Git=Yiy --+, Ggi=Yq)- 


— The type parameters of m, are X;...Xp, Y1... Yq. The bound of each type parameter, 
if any, is 8; applied to the corresponding type parameter bound in D or cy. 


— The return type of m,; is 8; applied to D<Fj,...,Fp>. 


— The (possibly empty) list of argument types of m; is 6; applied to the argument 
types of c,. 


— The (possibly empty) list of thrown types of m; is 9; applied to the thrown 
types of c. 


— The modifiers of m; are those of cj. 


— The name of m; is #m, an automatically generated name that is distinct from all 
constructor and method names in p and is shared by mj...mp. 


— The body of m; is irrelevant. 
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To choose a constructor, we temporarily consider m;...m, to be members of p. 
One of m;...m, 1s chosen, as determined by the class instance creation expression's 
argument expressions, using the process specified in §15.12.2. 


If there is no unique most specific method that is both applicable and accessible, 
then a compile-time error occurs. 


Otherwise, where m, is the chosen method: 


— If cis not an anonymous class, then c; is chosen as the constructor of c. 


The throws clause of the chosen constructor is the same as the throws clause 
determined for m,. 


The return type corresponding to the chosen constructor is the return type 
determined for m; (§15.12.2.6). 


If c is an anonymous class, then c's anonymous constructor is chosen as 
the constructor of c. Its body consists of an explicit constructor invocation 
($8.8.7.1) of cy. 


The throws clause of the chosen constructor includes the exceptions in the 
throws Clause determined for m. 


The return type corresponding to the chosen constructor is the anonymous 
class type. 


If the class instance creation expression is a poly expression, then its 
compatibility with a target type is as determined by §18.5.2.1, using m; as the 
selected method m. 


Testing for compatibility with a target type may occur multiple times before making 
a final determination of the class instance creation expression's target type and the 
return type corresponding to the chosen constructor. For example, an enclosing method 
invocation expression may require testing the class instance creation expression for 
compatibility with different methods' formal parameter types. 


If cis an anonymous class, then its superclass or superinterface (§15.9.5) is the 
return type determined for m; (§15.12.2.6). 


It is acompile-time error if the superclass or superinterface, or any subexpression 
therein ("subexpression" includes type arguments of parameterized types, 
bounds of wildcard type arguments, and element types of array types, but 
excludes bounds of type variables), has one of the following forms: 


— A type variable that was not declared as a type parameter (such as a type 


variable produced by capture conversion). 


EXPRESSIONS Class Instance Creation Expressions 


— An intersection type. 


— A class or interface type, where the class or interface declaration is not 
accessible from the class or interface in which the class instance creation 
expression appears. 


Itis acompile-time error if an argument to a class instance creation expression is not 
compatible with its target type, as derived from the invocation type (§15.12.2.6). 


If the compile-time declaration is applicable by variable arity invocation 
($15.12.2.4), then where the last formal parameter type of the invocation type of 
the constructor is F,[], it is a compile-time error if the type which is the erasure of 
F, 1s not accessible at the point of invocation. 


The type of the class instance creation expression is the return type corresponding 
to the chosen constructor, as defined above. 


15.9.4 Run-Time Evaluation of Class Instance Creation Expressions 


At run time, evaluation of a class instance creation expression is as follows. 


First, if the class instance creation expression is a qualified class instance creation 
expression, the qualifying primary expression is evaluated. If the qualifying 
expression evaluates to null, a NullPointerException is raised, and the class 
instance creation expression completes abruptly. If the qualifying expression 
completes abruptly, the class instance creation expression completes abruptly for 
the same reason. 


Next, space is allocated for the new class instance. If there is insufficient space to 
allocate the object, evaluation of the class instance creation expression completes 
abruptly by throwing an OutOfMemoryError. 


The new object contains new instances of all the fields declared in the specified 
class type and all its superclasses. As each new field instance is created, it is 
initialized to its default value (§4.12.5). 


Next, the actual arguments to the constructor are evaluated, left-to-right. If any of 
the argument evaluations completes abruptly, any argument expressions to its right 
are not evaluated, and the class instance creation expression completes abruptly for 
the same reason. 


Next, the selected constructor of the specified class type is invoked. This results 
in invoking at least one constructor for each superclass of the class type. This 
process can be directed by explicit constructor invocation statements (§8.8.7.1) and 
is specified in detail in $12.5. 
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The value of a class instance creation expression is a reference to the newly created 
object of the specified class. Every time the expression is evaluated, a fresh object 


is created. 


Example 15.9.4-1. Evaluation Order and Out-Of-Memory Detection 


If evaluation of a class instance creation expression finds there is insufficient memory to 
perform the creation operation, then an OutOfMemoryError is thrown. This check occurs 


before any argument expressions are evaluated. 
So, for example, the test program: 


class List { 
int value; 
List next; 
static List head = new List (0); 
List (int n) { value = n; next = head; head 
} 
class Test { 
public static void main(String[] args) { 
int id = 0, oldid = 0; 
try { 
for (77) { 
++id; 
new List (oldid = id); 
} 
} catch (Error e) { 
List.head = null; 


System.out.println(e.getClass() + ", " + (oldid==id)); 


prints: 


class java.lang.OutOfMemoryError, false 


because the out-of-memory condition is detected before the argument expression oldid 


= idis evaluated. 


Compare this to the treatment of array creation expressions, for which the out-of-memory 
condition is detected after evaluation of the dimension expressions (§15.10.2). 


15.9.5 Anonymous Class Declarations 


An anonymous class declaration is automatically derived from a class instance 


creation expression by the Java compiler. 


An anonymous class is never abstract (§8.1.1.1). 


= this; 


EXPRESSIONS 


} 
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An anonymous class is never final (§8.1.1.2). 


The fact that an anonymous class is not final is relevant in casting, in particular the 
narrowing reference conversion allowed for the cast operator (§5.5). It is also of interest 
in subclassing, in that it is impossible to declare a subclass of an anonymous class, despite 
an anonymous class being non-final, because an anonymous class cannot be named by 
an extends clause (§8.1.4). 


An anonymous class is always an inner class (§8.1.3); it is never static (§8.1.1, 
§8.5.1). 


The superclass or superinterface of an anonymous class is given by the class 
instance creation expression ($15.9.1), with type arguments inferred as necessary 
while choosing a constructor (§15.9.3). 


If the class instance creation expression uses <> with an anonymous class, then 
for all non-private methods declared in the anonymous class body, it is as if the 
method declaration is annotated with @override (§9.6.4.4). 


When <> is used, the inferred type arguments may not be as anticipated by the programmer. 
Consequently, the supertype of the anonymous class may not be as anticipated, and methods 
declared in the anonymous class may not override supertype methods as intended. Treating 
such methods as if annotated with @Override (if they are not explicitly annotated with 
@Override) helps avoid silently incorrect programs. 


15.9.5.1 Anonymous Constructors 


An anonymous class cannot have an explicitly declared constructor. Instead, an 
anonymous constructor is implicitly declared for an anonymous class. The form 
of the anonymous constructor for an anonymous class c with direct superclass s 
is as follows: 


e If sis not an inner class, or if sis a local class that occurs in a static context, then 
the anonymous constructor has one formal parameter for each actual argument 
to the class instance creation expression in which c is declared. 


The actual arguments to the class instance creation expression are used to 
determine a constructor cs of s, as specified by §15.9.3. The type of each formal 
parameter of the anonymous constructor must be identical to the corresponding 
formal parameter of cs. 


The constructor body consists of an explicit constructor invocation (§8.8.7.1) of 
the form super(...), where the actual arguments are the formal parameters of 
the constructor, in the order they were declared. The superclass constructor to 
be invoked is cs. 


515 


15.10 Array Creation and Access Expressions EXPRESSIONS 


¢ Otherwise, the first formal parameter of the constructor of c represents the 
value of the immediately enclosing instance of i with respect to s (§15.9.2, 
§15.9.3). The type of this parameter is the class type that immediately encloses 
the declaration of s. 


The constructor has an additional formal parameter for each actual argument to 
the class instance creation expression that declared the anonymous class. The 
n'th formal parameter e corresponds to the n-/'th actual argument. 


The actual arguments to the class instance creation expression are used to 
determine a constructor cs of s, as specified by §15.9.3. The type of each formal 
parameter of the anonymous constructor must be identical to the corresponding 
formal parameter of cs. 


The constructor body consists of an explicit constructor invocation (§8.8.7.1) of 
the form o.super(...), where o is the first formal parameter of the constructor, 
and the actual arguments are the subsequent formal parameters of the constructor, 
in the order they were declared. The superclass constructor to be invoked is cs 


In all cases, the throws clause of an anonymous constructor must list all the 
checked exceptions thrown by the explicit superclass constructor invocation 
statement contained within the anonymous constructor, as specified in §15.9.3, 
and all checked exceptions thrown by any instance initializers or instance variable 
initializers of the anonymous class. 


Note that it is possible for the signature of the anonymous constructor to refer 
to an inaccessible type (for example, if such a type occurred in the signature of 
the superclass constructor cs). This does not, in itself, cause any errors at either 
compile-time or run-time. 


15.10 Array Creation and Access Expressions 


15.10.1 Array Creation Expressions 


An array creation expression is used to create new arrays ($10 (Arrays)). 


ArrayCreationExpression: 
new PrimitiveType DimExprs [Dims] 
new ClassOrInterfaceType DimExprs [Dims] 
new PrimitiveType Dims ArrayInitializer 
new ClassOrInterfaceType Dims ArraylInitializer 
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DimExprs: 
DimExpr {DimExpr} 


DimExpr: 
{Annotation} | Expression ] 


The following production from §4.3 is shown here for convenience: 


Dims: 
{Annotation} [| ] {{Annotation} [ ]} 


An array creation expression creates an object that is a new array whose elements 
are of the type specified by the PrimitiveType or ClassOrInterfaceType. 


It is a compile-time error if the ClassOrInterfaceType does not denote a reifiable 
type ($4.7). Otherwise, the ClassOrInterfaceType may name any named reference 
type, even an abstract class type (§8.1.1.1) or an interface type. 


The rules above imply that the element type in an array creation expression cannot be a 
parameterized type, unless all type arguments to the parameterized type are unbounded 
wildcards. 


The type of each dimension expression within a DimExpr must be a type that is 
convertible (§5.1.8) to an integral type, or a compile-time error occurs. 


Each dimension expression undergoes unary numeric promotion (§5.6.1). The 
promoted type must be int, or a compile-time error occurs. 


The type of the array creation expression is an array type that can denoted by a copy 
of the array creation expression from which the new keyword and every DimExpr 
expression and array initializer have been deleted. 


For example, the type of the creation expression: 
new double[3] [3] [] 
is: 


double[][][] 


15.10.2. Run-Time Evaluation of Array Creation Expressions 


At run time, evaluation of an array creation expression behaves as follows: 


¢ If there are no dimension expressions, then there must be an array initializer. A 
newly allocated array will be initialized with the values provided by the array 
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initializer as described in §10.6. The value of the array initializer becomes the 
value of the array creation expression. 


Otherwise, there is no array initializer, and: 


— First, the dimension expressions are evaluated, left-to-right. If any of the 
expression evaluations completes abruptly, the expressions to the right of it 
are not evaluated. 


— Next, the values of the dimension expressions are checked. If the value of any 
DimExpr expression is less than zero, then a NegativeArraySizeException 
is thrown. 


— Next, space is allocated for the new array. If there is insufficient space 
to allocate the array, evaluation of the array creation expression completes 
abruptly by throwing an OutOfMemoryError. 


— Then, if a single DimExpr appears, a one-dimensional array is created of the 
specified length, and each component of the array is initialized to its default 
value (§4.12.5). 


— Otherwise, if n DimExpr expressions appear, then array creation effectively 
executes a set of nested loops of depth n-1 to create the implied arrays of 
arrays. 


A multidimensional array need not have arrays of the same length at each level. 


Example 15.10.2-1. Array Creation Evaluation 


In an array creation expression with one or more dimension expressions, each dimension 
expression is fully evaluated before any part of any dimension expression to its right. Thus: 


class Testl { 
public static void main(String[] args) { 
int i = 4; 
int ia[][] = new int[i] [i=3]; 
System.out.print1n ( 
"[" + ia.length + "," + ia[0].length + "]"); 


prints: 
[4,3] 


because the first dimension is calculated as 4 before the second dimension expression sets 
ito 3. 


EXPRESSIONS Array Creation and Access Expressions 
If evaluation of a dimension expression completes abruptly, no part of any dimension 
expression to its right will appear to have been evaluated. Thus: 


class Test2 { 
public static void main(String[] args) { 


int[][] a = { { 00, 01 }, { 10, 11 } }; 
int i = 99; 
try { 
a[val()][i = 1]++; 
} catch (Exception e) { 
System.out.println(e + ", i=" + i); 


} 
static int val() throws Exception { 
throw new Exception ("unimplemented") ; 


prints: 
java.lang.Exception: unimplemented, i=99 
because the embedded assignment that sets i to 1 is never executed. 
Example 15.10.2-2. Multi-Dimensional Array Creation 
The declaration: 
float[][] matrix = new float[3] [3]; 


is equivalent in behavior to: 


float[][] matrix = new float[3][]; 
for (int d = 0; d < matrix.length; dt++) 
matrix[d] = new float[3]; 
and: 
Age[][][]{]{] Aquarius = new Age[6][10] [8] [12] [1]; 


is equivalent to: 
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Age[][][][][] Aquarius = new Age[l6] [I] [] [1] [1]; 
for (int dl = 0; dl < Aquarius.length; dil++) { 


Aquarius[d1] = new Age[10][] [][]; 
for (int d2 = 0; d2 < Aquarius[di].length; d2++) { 
Aquarius[d1][d2] = new Age[8][1][]; 


for (int d3 = 0; d3 < Aquarius[d1][d2].length; d3++) { 
Aquarius[d1][d2][d3] = new Age[12][]; 


with d, dl, d2, and d3 replaced by names that are not already locally declared. Thus, a 
single new expression actually creates one array of length 6, 6 arrays of length 10, 6x10 
= 60 arrays of length 8, and 6x10x8 = 480 arrays of length 12. This example leaves the 
fifth dimension, which would be arrays containing the actual array elements (references to 


Age objects), initialized only to null references. These arrays can be filled in later by other 
code, such as: 


Age[] Hair = { new Age("quartz"), new Age("topaz") }; 
Aquarius[1][9][6][9] = Hair; 


A triangular matrix may be created by: 


float triang[][] = new float[100][]; 
for (int i = 0; i < triang.length; i++) 
triang[i] = new float[i+l]; 

If evaluation of an array creation expression finds there is insufficient memory to 
perform the creation operation, then an OutOfMemoryError is thrown. If the array 
creation expression does not have an array initializer, then this check occurs only 
after evaluation of all dimension expressions has completed normally. If the array 
creation expression does have an array initializer, then an OutofMemoryError can 
occur when an object of reference type is allocated during evaluation of a variable 
initializer expression, or when space is allocated for an array to hold the values of 
a (possibly nested) array initializer. 


Example 15.10.2-3. outofMemoryError and Dimension Expression Evaluation 


class Test3 { 
public static void main(String[] args) { 
int len = 0, oldlen = 0; 
Object[] a = new Object [0]; 


try { 
for (77) { 
++ len; 
Object [] temp = new Object [oldlen = len]; 
temp[0] = a; 


a = temp; 
} 
} catch (Error e) { 
System.out.println(e + ", " + (oldlen==len) ); 
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} 
This program produces the output: 
java.lang.OutOfMemoryError, true 


because the out-of-memory condition is detected after the dimension expression oldlen 
= len is evaluated. 


Compare this to class instance creation expressions (§15.9), which detect the out-of- 
memory condition before evaluating argument expressions (§15.9.4). 


15.10.3 Array Access Expressions 


An array access expression refers to a variable that is a component of an array. 


ArrayAccess: 
ExpressionName [{ Expression J 
PrimaryNoNewArray [ Expression ] 


An atray access expression contains two subexpressions, the array reference 
expression (before the left bracket) and the index expression (within the brackets). 


Note that the array reference expression may be a name or any primary expression that is 
not an array creation expression (§15.10). 


The type of the array reference expression must be an array type (call it T[], an 
array whose components are of type T), or a compile-time error occurs. 


The index expression undergoes unary numeric promotion (§5.6.1). The promoted 
type must be int, or a compile-time error occurs. 


The type of the array access expression is the result of applying capture conversion 
(§5.1.10) to r. 


The result of an array access expression is a variable of type 7, namely the variable 
within the array selected by the value of the index expression. 


This resulting variable, which is a component of the array, is never considered 
final, even if the array reference expression denoted a final variable. 


15.10.4 Run-Time Evaluation of Array Access Expressions 


At run time, evaluation of an array access expression behaves as follows: 


15.10 


521 


15.10 


522 


Array Creation and Access Expressions EXPRESSIONS 


¢ First, the array reference expression is evaluated. If this evaluation completes 
abruptly, then the array access completes abruptly for the same reason and the 
index expression is not evaluated. 


¢ Otherwise, the index expression is evaluated. If this evaluation completes 
abruptly, then the array access completes abruptly for the same reason. 


¢ Otherwise, if the value of the array reference expression is null, then a 
NullPointerException is thrown. 


¢ Otherwise, the value of the array reference expression indeed refers to an array. 
If the value of the index expression is less than zero, or greater than or equal to 
the array's Length, then an ArrayIndexOut OfBoundsExcept ion is thrown. 


¢ Otherwise, the result of the array access is the variable of type 1, within the array, 
selected by the value of the index expression. 


Example 15.10.4-1. Array Reference Is Evaluated First 


In an array access, the expression to the left of the brackets appears to be fully evaluated 
before any part of the expression within the brackets is evaluated. For example, in the 
(admittedly monstrous) expression a[ (a=b) [3]], the expression a is fully evaluated 
before the expression (a=b) [3]; this means that the original value of a is fetched and 
remembered while the expression (a=b) [3] is evaluated. This array referenced by the 
original value of a is then subscripted by a value that is element 3 of another array (possibly 
the same array) that was referenced by b and is now also referenced by a. 


Thus, the program: 


class Testl { 
public static void main(String[] args) { 
int[] a = { 11, 12, 13, 14 }; 
int[] b £0} Lp Be 3H; 
System.out.printin(a[(a=b) [3]]); 


} 
prints: 

14 
because the monstrous expression's value is equivalent to a[b[3]] or a[3] or 14. 
Example 15.10.4-2. Abrupt Completion of Array Reference Evaluation 


If evaluation of the expression to the left of the brackets completes abruptly, no part of the 
expression within the brackets will appear to have been evaluated. Thus, the program: 


class Test2 { 
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public static void main(String[] args) { 
int index = 1; 
try { 
skedaddle() [index=2]++; 
} catch (Exception e) { 
System.out.println(e + ", index=" + index); 


} 
static int[] skedaddle() throws Exception { 
throw new Exception("Ciao") ; 


prints: 

java.lang.Exception: Ciao, index=1 
because the embedded assignment of 2 to index never occurs. 
Example 15.10.4-3. nu11 Array Reference 


If the array reference expression produces nu11 instead of a reference to an array, then a 
NullPointerExcept ion is thrown at run time, but only after all parts of the array access 
expression have been evaluated and only if these evaluations completed normally. Thus, 
the program: 


class Test3 { 
public static void main(String[] args) { 


int index = 1; 
try { 
nada () [index=2]++; 


} catch (Exception e) { 
System.out.printlin(e + ", index=" + index); 


} 


static int[] nada() { return null; } 


prints: 
java.lang.NullPointerException, index=2 


because the embedded assignment of 2 to index occurs before the check for a nul1 array 
reference expression. As a related example, the program: 


class Test4 { 
public static void main(String[] args) { 
int[] a = null; 
try { 
int i = a[vamoose()]; 
System.out.printin(i); 
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} catch (Exception e) { 
System.out.printin(e); 
} 
} 
static int vamoose() throws Exception { 
throw new Exception("Twenty-three skidoo!"); 
} 
} 


always prints: 
java.lang.Exception: Twenty-three skidoo! 


A NullPointerException never occurs, because the index expression must be 
completely evaluated before any further part of the array access occurs, and that includes 
the check as to whether the value of the array reference expression is null. 


15.11 Field Access Expressions 


A field access expression may access a field of an object or array, a reference to 
which is the value of either an expression or the special keyword super. 


FieldAccess: 
Primary . Identifier 
super . Identifier 
TypeName . super . Identifier 


The meaning of a field access expression is determined using the same rules as for 
qualified names (§6.5.6.2), but limited by the fact that an expression cannot denote 
a package, class type, or interface type. 


It is also possible to refer to a field of the current instance or current class by using 
a simple name (§6.5.6.1). 


15.11.1 Field Access Using a Primary 


The type of the Primary must be a reference type rT, or a compile-time error occurs. 
The meaning of the field access expression is determined as follows: 


¢ If the identifier names several accessible ($6.6) member fields in type r, then the 
field access is ambiguous and a compile-time error occurs. 


¢ If the identifier does not name an accessible member field in type r, then the 
field access is undefined and a compile-time error occurs. 
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¢ Otherwise, the identifier names a single accessible member field in type 7, and 
the type of the field access expression is the type of the member field after capture 
conversion (§5.1.10). 


At run time, the result of the field access expression is computed as follows: 
(assuming that the program is correct with respect to definite assignment analysis, 
that is, every blank final variable is definitely assigned before access) 


¢ If the field is static: 


— The Primary expression is evaluated, and the result is discarded. If evaluation 
of the Primary expression completes abruptly, the field access expression 
completes abruptly for the same reason. 


— If the field is a non-blank final field, then the result is the value of the 
specified class variable in the class or interface that is the type of the Primary 
expression. 


— If the field is not final, or is a blank final and the field access occurs in a 
class variable initializer (§8.3.2) or static initializer (§8.7), then the result is 
a variable, namely, the specified class variable in the class that is the type of 
the Primary expression. 


e If the field is not static: 


— The Primary expression is evaluated. If evaluation of the Primary expression 
completes abruptly, the field access expression completes abruptly for the 
same reason. 


— If the value of the Primary is nu11, then a Nul1lPointerException is thrown. 


— If the field is a non-blank final, then the result is the value of the named 
member field in type r found in the object referenced by the value of the 
Primary. 


— If the field is not final, or is a blank final and the field access occurs in an 
instance variable initializer (§8.3.2), instance initializer ($8.6), or constructor 
($8.8), then the result is a variable, namely the named member field in type rT 
found in the object referenced by the value of the Primary. 


Note that only the type of the Primary expression, not the class of the actual object 
referred to at run time, is used in determining which field to use. 
Example 15.11.1-1. Static Binding for Field Access 
class § { int x = 0; } 


class T extends S { int x = 1; } 
class Testl { 
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public static void main(String[] args) { 
Tt = new T(); 
System.out.println("t.x=" + t.x + when("t", t)); 
Ss = new S(); 
System.out.println("s.x=" + s.x + when("s", s)); 
s=t; 
System.out.println("s.x=" + s.x + when("s", s)); 
} 
static String when(String name, Object t) { 
return " when " + name + " holds a " 
+ t.getClass() + " at run time."; 


This program produces the output: 


t.x=l1 when t holds a class T at run time. 
s.x=0 when s holds a class S at run time. 
s.x=0 when s holds a class T at run time. 


The last line shows that, indeed, the field that is accessed does not depend on the run- 
time class of the referenced object; even if s holds a reference to an object of class T, the 
expression s.x refers to the x field of class s, because the type of the expression s is S. 
Objects of class T contain two fields named x, one for class T and one for its superclass Ss. 


This lack of dynamic lookup for field accesses allows programs to be run efficiently with 
straightforward implementations. The power of late binding and overriding is available, but 
only when instance methods are used. Consider the same example using instance methods 
to access the fields: 


class § { int x = 0; int z() { return x; } } 
class T extends S { int x 
class Test2 { 
public static void main(String[] args) { 
Tt = new T(); 


1; int z() { return x; } } 


System.out.println("t.z()=" + t.z() + when("t", t)); 
Ss = new S(); 

System.out.println("s.z()=" + s.z() + when("s", s)); 
s=t; 

System.out.println("s.z()=" + s.z() + when("s", s)); 


} 
static String when(String name, Object t) { 
return " when " + name + " holds a " 
+ t.getClass() + " at run time."; 


Now the output is: 


)=1 when t holds a class T at run time. 
-zZ()=0 when s holds a class S at run time. 
+Z() 


wae Ag | 
s 
s =1 when s holds a class T at run time. 
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The last line shows that, indeed, the method that is accessed does depend on the run- 
time class of the referenced object; when s holds a reference to an object of class T, the 
expression s.z() refers to the z method of class T, despite the fact that the type of the 
expression s is S. Method z of class T overrides method z of class s. 


Example 15.11.1-2. Receiver Variable Is Irrelevant For st atic Field Access 


The following program demonstrates that a null reference may be used to access a class 
(static) variable without causing an exception: 


class Test3 { 

static String mountain = "Chocorua"; 

static Test3 favorite() { 
System.out.print ("Mount "); 
return null; 

} 

public static void main(String[] args) { 
System.out.println(favorite().mountain) ; 


} 


It compiles, executes, and prints: 
Mount Chocorua 


Even though the result of favorite () isnull,aNullPointerException is not thrown. 
That "Mount "is printed demonstrates that the Primary expression is indeed fully evaluated 
at run time, despite the fact that only its type, not its value, is used to determine which field 
to access (because the field mountain is static). 


15.11.2 Accessing Superclass Members using super 


The form super . Identifier refers to the field named Identifier of the current object, 
but with the current object viewed as an instance of the superclass of the current 
class. 


The form T.super.J/dentifier refers to the field named Identifier of the lexically 
enclosing instance corresponding to T, but with that instance viewed as an instance 
of the superclass of T. 


The forms using the keyword super are valid only in an instance method, instance 
initializer, or constructor of a class, or in the initializer of an instance variable of a 
class. If they appear anywhere else, a compile-time error occurs. 


These are exactly the same situations in which the keyword this may be used in a class 
declaration (§ 15.8.3). 
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It is a compile-time error if the forms using the keyword super appear in the 
declaration of class object, since Object has no superclass. 


Suppose that a field access expression super. f appears within class c, and the 
immediate superclass of cis class s. If fin sis accessible from class c (§6.6), then 
super. f is treated as if it had been the expression this. f in the body of class s. 
Otherwise, a compile-time error occurs. 


Thus, super. f can access the field f£ that is accessible in class s, even if that field is hidden 
by a declaration of a field £ in class c. 


Suppose that a field access expression T. super. f appears within class c, and the 
immediate superclass of the class denoted by ris a class whose fully qualified name 
is s. If fin sis accessible from c, then T. super. f is treated as if it had been the 
expression this. f£ in the body of class s. Otherwise, a compile-time error occurs. 


Thus, T. super. f can access the field f that is accessible in class s, even if that field is 
hidden by a declaration of a field fin class T. 


It is a compile-time error if the current class is not an inner class of class Tor ritself. 


Example 15.11.2-1. The super Expression 


interface I > dint: x=: Oey FT 
class Tl implements I { int x = 1; } 
class T2 extends Tl { int x = 2; } 
class T3 extends T2 { 

int x = 3; 


void test() { 
System.out.printin("x=\t\t" + x); 
System.out.printin("super.x=\t\t" + super.x); 
T2)this) .x=\t" + ((T2)this) .x); 
+ ((T1)this).x); 
+ 


( 
( 
System.out.printin(" 
( 
( ((I) this) .x); 


(( 
System.out.println("((T1) this) .x=\t" 
System.out.printin("((I)this) .x=\t" 
} 
} 
class Test { 
public static void main(String[] args) { 
new T3().test(); 


} 


This program produces the output: 


x= 3 
super.x= 2 
((T2) this) .x= 2 
((T1) this) .x= 1 
((I) this) .x= 0 
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Within class T3, the expression super. x has the same effect as ((T2) this) .x when x 
has package access. Note that super . x is not specified in terms of a cast, due to difficulties 
around access to protected members of the superclass. 


15.12 Method Invocation Expressions 


A method invocation expression is used to invoke a class or instance method. 


MethodInvocation: 
MethodName ( [ArgumentList] ) 
TypeName . [TypeArguments] Identifier ( [ArgumentList] ) 
ExpressionName . [TypeArguments] Identifier ( [ArgumentList] ) 
Primary . [TypeArguments] Identifier ( [ArgumentList] ) 
super . [TypeArguments] Identifier ( [ArgumentList] ) 
TypeName . super . [TypeArguments] Identifier ( [ArgumentList] ) 


ArgumentList: 
Expression {, Expression} 


Resolving a method name at compile time is more complicated than resolving a 
field name because of the possibility of method overloading. Invoking a method at 
run time is also more complicated than accessing a field because of the possibility 
of instance method overriding. 


Determining the method that will be invoked by a method invocation expression 
involves several steps. The following three sections describe the compile-time 
processing of a method invocation. The determination of the type of the method 
invocation expression is specified in §15.12.3. 


The exception types that a method invocation expression can throw are specified 
in §11.2.1. 


wom 


It is a compile-time error if the name to the left of the rightmost "." that occurs 
before the ( in a MethodInvocation cannot be classified as a TypeName or an 
ExpressionName (§6.5.2). 


If TypeArguments is present to the left of Identifier, then it is a compile-time error 
if any of the type arguments are wildcards (§4.5.1). 


A method invocation expression is a poly expression if all of the following are true: 


¢ The invocation appears in an assignment context or an invocation context (§5.2, 
§5.3). 
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¢ If the invocation is qualified (that is, any form of MethodInvocation except for 
the first), then the invocation elides TypeArguments to the left of the Identifier. 


¢ The method to be invoked, as determined by the following subsections, is generic 
($8.4.4) and has a return type that mentions at least one of the method's type 
parameters. 


Otherwise, the method invocation expression is a standalone expression. 


15.12.1_ Compile-Time Step 1: Determine Class or Interface to Search 


The first step in processing a method invocation at compile time is to figure out 
the name of the method to be invoked and which class or interface to search for 
definitions of methods of that name. 


The name of the method is specified by the MethodName or Identifier which 
immediately precedes the left parenthesis of the MethodInvocation. 


For the class or interface to search, there are six cases to consider, depending on 
the form that precedes the left parenthesis of the MethodInvocation: 


¢ If the form is MethodName, that is, just an Identifier, then: 


If the Identifier appears in the scope of a method declaration with that name 
(§6.3, §6.4.1), then: 


— If there is an enclosing type declaration of which that method is a member, let 
T be the innermost such type declaration. The class or interface to search is T. 


This search policy is called the "comb rule". It effectively looks for methods in a 
nested class's superclass hierarchy before looking for methods in an enclosing class 
and its superclass hierarchy. See §6.5.7.1 for an example. 

— Otherwise, the method declaration may be in scope due to one or more 
single-static-import or static-import-on-demand declarations. There is no class 
or interface to search, as the method to be invoked is determined later 
(§15.12.2.1). 


¢ If the form is TypeName . [TypeArguments] Identifier, then the type to search 
is the type denoted by TypeName. 


¢ If the form is ExpressionName . [TypeArguments] Identifier, then the class 
or interface to search is the declared type r of the variable denoted by 
ExpressionName if T is a class or interface type, or the upper bound of rif ris 
a type variable. 
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¢ Ifthe form is Primary . [TypeArguments] Identifier, then let T be the type of the 
Primary expression. The class or interface to search is rif Tis a class or interface 
type, or the upper bound of rif Tis a type variable. 


It is a compile-time error if Tis not a reference type. 


¢ If the form is super . [TypeArguments] Identifier, then the class to search is the 
superclass of the class whose declaration contains the method invocation. 


Let r be the type declaration immediately enclosing the method invocation. It is 
a compile-time error if Tis the class object or Tis an interface. 


¢ If the form is TypeName . super . [TypeArguments] Identifier, then: 
— Itis a compile-time error if TypeName denotes neither a class nor an interface. 
— If TypeName denote a class, c, then the class to search is the superclass of c. 


It is a compile-time error if c is not a lexically enclosing type declaration of 
the current class, or if cis the class Object. 


Let r be the type declaration immediately enclosing the method invocation. It 
is a compile-time error if Tis the class Object. 


— Otherwise, TypeName denotes the interface to be searched, r. 


Let r be the type declaration immediately enclosing the method invocation. It 
is a compile-time error if Z is not a direct superinterface of r, or if there exists 
some other direct superclass or direct superinterface of rT, J, such that vis a 
subtype of 1. 


The TypeName . super syntax is overloaded: traditionally, the TypeName refers to a 
lexically enclosing type declaration which is a class, and the target is the superclass of 
this class, as if the invocation were an unqualified super in the lexically enclosing type 
declaration. 


class Superclass { 
void foo() { System.out.printin("Hi"); } 
} 


class Subclassl extends Superclass { 


void foo() { throw new UnsupportedOperationException(); } 
Runnable tweak = new Runnable() { 
void run() { 


Subclassl.super.foo(); // Gets the 'printin' behavior 
} 
‘i 
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To support invocation of default methods in superinterfaces, the TypeName may also 
refer to a direct superinterface of the current class or interface, and the target is that 
superinterface. 


interface Superinterface { 
default void foo() { System.out.println("Hi"); } 
} 


class Subclass2 implements Superinterface { 
void foo() { throw new UnsupportedOperationException(); } 


void tweak() { 
Superinterface.super.foo(); // Gets the 'println' behavior 


} 


No syntax supports a combination of these forms, that is, invoking a superinterface method 
of a lexically enclosing type declaration which is a class, as if the invocation were of the 
form InterfaceName . super in the lexically enclosing type declaration. 


class Subclass3 implements Superinterface { 


void foo() { throw new UnsupportedOperationException(); } 
Runnable tweak = new Runnable() { 
void run() { 


Subclass3.Superinterface.super.foo(); // Illegal 
} 
}; 


A workaround is to introduce a private method in the lexically enclosing type declaration, 
that performs the interface super call. 


15.12.2 Compile-Time Step 2: Determine Method Signature 


The second step searches the type determined in the previous step for member 
methods. This step uses the name of the method and the argument expressions to 
locate methods that are both accessible and applicable, that is, declarations that 
can be correctly invoked on the given arguments. 


There may be more than one such method, in which case the most specific one is 
chosen. The descriptor (signature plus return type) of the most specific method is 
the one used at run time to perform the method dispatch. 


Certain argument expressions that contain implicitly typed lambda expressions 
($15.27.1) or inexact method references (§15.13.1) are ignored by the applicability 
tests, because their meaning cannot be determined until the invocation's target type 
is selected. On the other hand, it is only argument expressions - not the invocation's 
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target type - that influence the applicability tests, even if the method invocation 
expression is a poly expression. 


The process of determining applicability begins by determining the potentially 
applicable methods (§15.12.2.1). Then, to ensure compatibility with the Java 
programming language prior to Java SE 5.0, the process continues in three phases: 


1. The first phase performs overload resolution without permitting boxing or 
unboxing conversion, or the use of variable arity method invocation. If no 
applicable method is found during this phase then processing continues to the 
second phase. 


This guarantees that any calls that were valid in the Java programming language 
before Java SE 5.0 are not considered ambiguous as the result of the introduction of 
variable arity methods, implicit boxing and/or unboxing. However, the declaration of 
a variable arity method (§8.4.1) can change the method chosen for a given method 
method invocation expression, because a variable arity method is treated as a fixed 
arity method in the first phase. For example, declaring m (Object...) inaclass which 
already declares m(Object) causes m(Object) to no longer be chosen for some 
invocation expressions (such as m(nul1l) ), aS m(Object []) is more specific. 
2. The second phase performs overload resolution while allowing boxing and 
unboxing, but still precludes the use of variable arity method invocation. If no 
applicable method is found during this phase then processing continues to the 


third phase. 


This ensures that a method is never chosen through variable arity method invocation 
if it is applicable through fixed arity method invocation. 
3. The third phase allows overloading to be combined with variable arity methods, 
boxing, and unboxing. 


A method is applicable if it is applicable by one of strict invocation (the first phase, 
§15.12.2.2), loose invocation (the second phase, §15.12.2.3), or variable arity 
invocation (the third phase, §15.12.2.4). Deciding whether a method is applicable 
will, in the case of generic methods (§8.4.4), require an analysis of the type 
arguments. Type arguments may be passed explicitly or implicitly; if they are 
passed implicitly, then bounds of the type arguments must be inferred from the 
argument expressions (§18 (Type Inference)). 


If several applicable methods have been identified during one of the three phases 
of applicability testing, then the most specific one is chosen, as specified in section 
§15.12.2.5. 


To check for applicability, the types of an invocation's arguments cannot, in general, be 
inputs to the analysis. This is because: 
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¢ The arguments to a method invocation may be poly expressions. 
¢ Poly expressions cannot be typed in the absence of a target type. 


* Overload resolution has to be completed before the arguments’ target types will be 
known. 


Instead, the input to the applicability check is a list of the arguments themselves. The 
arguments can be checked for compatibility with potential target types, even if the ultimate 
types of the arguments are unknown. 


Note that overload resolution is independent of a target type. This is for two reasons: 


¢ First, it makes the user model more accessible and less error-prone. The meaning of 
a method name (i.e., the declaration corresponding to the name) is too fundamental to 
the meaning of a program to depend on subtle contextual hints. (In contrast, other poly 
expressions may have different behavior depending on a target type; but the variation in 
behavior is always limited and essentially equivalent, while no such guarantees can be 
made about the behavior of an arbitrary set of methods that share a name and arity.) 


* Second, it allows other properties - such as whether or not the method is a poly expression 
(§15.12) or how to categorize a conditional expression (§15.25) - to depend on the 
meaning of the method name, even before a target type is known. 


Example 15.12.2-1. Method Applicability 


class Doubler { 
static int two() { return two(1l); } 
private static int two(int i) { return 2*i; } 
} 
class Test extends Doubler { 
static long two(long j) { return j+j; } 


public static void main(String[] args) { 
System.out.printin (two (3)); 
System.out.printin(Doubler.two(3)); // compile-time error 


For the method invocation two (1) within class Doubler, there are two accessible methods 
named two, but only the second one is applicable, and so that is the one invoked at run time. 


For the method invocation two (3) within class Test, there are two applicable methods, 
but only the one in class Test is accessible, and so that is the one to be invoked at run time 
(the argument 3 is converted to type Long). 


For the method invocation Doubler.two(3), the class Doubler, not class Test, is 
searched for methods named two; the only applicable method is not accessible, and so this 
method invocation causes a compile-time error. 


Another example is: 
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class ColoredPoint { 
int x, y; 
byte color; 
void setColor(byte color) { this.color = color; } 
} 
class Test { 
public static void main(String[] args) { 
ColoredPoint cp = new ColoredPoint (); 
byte color = 37; 
cp.setColor(color) ; 
cp.setColor(37); // compile-time error 


Here, a compile-time error occurs for the second invocation of setColor, because no 
applicable method can be found at compile time. The type of the literal 37 is int, and 
int cannot be converted to byte by invocation conversion. Assignment conversion, which 
is used in the initialization of the variable color, performs an implicit conversion of the 
constant from type int to byte, which is permitted because the value 37 is small enough to 
be represented in type byte; but such a conversion is not allowed for invocation conversion. 


If the method set Color had, however, been declared to take an int instead of a byte, then 
both method invocations would be correct; the first invocation would be allowed because 
invocation conversion does permit a widening conversion from byte to int. However, a 
narrowing cast would then be required in the body of set Color: 


void setColor(int color) { this.color = (byte)color; } 
Here is an example of overloading ambiguity. Consider the program: 


class Point { int x, y; } 
class ColoredPoint extends Point { int color; } 
class Test { 
static void test (ColoredPoint p, Point q) { 
System.out.println("(ColoredPoint, Point)"); 
} 
static void test (Point p, ColoredPoint q) { 
System.out.println("(Point, ColoredPoint)"); 
} 
public static void main(String[] args) { 
ColoredPoint cp = new ColoredPoint (); 
test(cp, cp); // compile-time error 


This example produces an error at compile time. The problem is that there are two 
declarations of test that are applicable and accessible, and neither is more specific than 
the other. Therefore, the method invocation is ambiguous. 


If a third definition of test were added: 
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static void test (ColoredPoint p, ColoredPoint q) { 
System.out.printin("(ColoredPoint, ColoredPoint)"); 


then it would be more specific than the other two, and the method invocation would no 
longer be ambiguous. 


Example 15.12.2-2. Return Type Not Considered During Method Selection 


class Point { int x, y; } 
class ColoredPoint extends Point { int color; } 
class Test { 
static int test (ColoredPoint p) { 
return p.color; 
} 
static String test (Point p) { 
return "Point"; 
} 
public static void main(String[] args) { 
ColoredPoint cp = new ColoredPoint (); 
String s = test(cp); // compile-time error 


Here, the most specific declaration of method test is the one taking a parameter of type 
ColoredPoint. Because the result type of the method is int, a compile-time error occurs 
because an int cannot be converted to a St ring by assignment conversion. This example 
shows that the result types of methods do not participate in resolving overloaded methods, 
so that the second test method, which returns a St ring, is not chosen, even though it has 
a result type that would allow the example program to compile without error. 


Example 15.12.2-3. Choosing The Most Specific Method 


The most specific method is chosen at compile time; its descriptor determines what method 
is actually executed at run time. If a new method is added to a class, then source code that 
was compiled with the old definition of the class might not use the new method, even if a 
recompilation would cause this method to be chosen. 


So, for example, consider two compilation units, one for class Point: 


package points; 
public class Point { 
public int x, y; 
public Point(int x, int y) { this.x = x; this.y = y; } 
public String toString() { return toString(""); } 
public String toString(String s) { 
return "("+x+","+yt+s+ ")"; 


and one for class ColoredPoint: 


536 


EXPRESSIONS Method Invocation Expressions 


package points; 
public class ColoredPoint extends Point { 
public static final int 
RED = 0, GREEN = 1, BLUE = 2; 
public static String[] COLORS = 
{ "red", "green", "blue" }; 


public byte color; 
public ColoredPoint (int x, int y, int color) { 
super (x, y); 


this.color (byte) color; 


/** Copy all relevant fields of the argument into 
this ColoredPoint object. */ 
public void adopt (Point p) { x = p.x; y =p.y; } 


public String toString() { 
String s = "," + COLORS[color]; 
return super.toString(s); 


Now consider a third compilation unit that uses ColoredPoint: 


import points.*; 
class Test { 
public static void main(String[] args) { 
ColoredPoint cp = 
new ColoredPoint (6, 6, ColoredPoint.RED) ; 
ColoredPoint cp2 = 
new ColoredPoint (3, 3, ColoredPoint.GREEN) ; 
cp.adopt (cp2) ; 
System.out.println("cp: " + cp); 


The output is: 
cp: (3,3,red) 


The programmer who coded class Test has expected to see the word green, because the 
actual argument, a ColoredPoint, has a color field, and color would seem to be a 
"relevant field". (Of course, the documentation for the package points ought to have been 
much more precise!) 


Notice, by the way, that the most specific method (indeed, the only applicable method) for 
the method invocation of adopt has a signature that indicates a method of one parameter, 
and the parameter is of type Point. This signature becomes part of the binary representation 
of class Test produced by the Java compiler and is used by the method invocation at run 
time. 


15.12 


537 


15.12 


538 


Method Invocation Expressions EXPRESSIONS 


Suppose the programmer reported this software error and the maintainer of the points 
package decided, after due deliberation, to correct it by adding a method to class 
ColoredPoint 


public void adopt (ColoredPoint p) { 
adopt ((Point)p); 
color = p.color; 


If the programmer then runs the old binary file for Test with the new binary file for 
ColoredPoint, the output is still: 


cp: (3,3,red) 


because the old binary file for Test still has the descriptor "one parameter, whose type 
is Point; void" associated with the method call cp.adopt (cp2). If the source code for 
Test is recompiled, the Java compiler will then discover that there are now two applicable 
adopt methods, and that the signature for the more specific one is "one parameter, whose 
type is ColoredPoint; void"; running the program will then produce the desired output: 


cp: (3,3,green) 


With forethought about such problems, the maintainer of the points package could fix the 
ColoredPoint class to work with both newly compiled and old code, by adding defensive 
code to the old adopt method for the sake of old code that still invokes it on ColoredPoint 
arguments: 


public void adopt (Point p) { 
if (p instanceof ColoredPoint) 
color = ((ColoredPoint)p).color; 
xX = p.xX; Y = P-y; 


Ideally, source code should be recompiled whenever code that it depends on is 
changed. However, in an environment where different classes are maintained by different 
organizations, this is not always feasible. Defensive programming with careful attention 
to the problems of class evolution can make upgraded code much more robust. See §13 
(Binary Compatibility) for a detailed discussion of binary compatibility and type evolution. 


15.12.2.1 Identify Potentially Applicable Methods 


The class or interface determined by compile-time step 1 (§$15.12.1) is searched 
for all member methods that are potentially applicable to this method invocation; 
members inherited from superclasses and superinterfaces are included in this 
search. 


In addition, if the form of the method invocation expression is MethodName - 
that is, a single Identifier - then the search for potentially applicable methods 
also examines all member methods that are imported by single-static-import 
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declarations and static-import-on-demand declarations of the compilation unit 
where the method invocation occurs (§7.5.3, §7.5.4) and that are not shadowed at 
the point where the method invocation appears. 


A member method is potentially applicable to a method invocation if and only if 
all of the following are true: 


¢ The name of the member is identical to the name of the method in the method 
invocation. 


¢ The member is accessible (§6.6) to the class or interface in which the method 
invocation appears. 


Whether a member method is accessible at a method invocation depends on the access 
modifier (public, protected, no modifier (package access), or private) in the 
member's declaration, and on the inheritance of the member by the class or interface 
determined by compile-time step 1, and on where the method invocation appears. 


e If the member is a fixed arity method with arity n, the arity of the method 
invocation is equal to n, and for all i (1 <i <n), the 7’th argument of the method 
invocation is potentially compatible, as defined below, with the type of the 7th 
parameter of the method. 


¢ If the member is a variable arity method with arity n, then for all i (1 <i <n-1), 
the i'th argument of the method invocation is potentially compatible with the type 
of the ‘th parameter of the method; and, where the nth parameter of the method 
has type T[], one of the following is true: 


— The arity of the method invocation is equal to n-1. 


— The arity of the method invocation is equal to n, and the nth argument of the 
method invocation is potentially compatible with either ror T[]. 


— The arity of the method invocation is m, where m > n, and for alli(n <i<m), 
the i'th argument of the method invocation is potentially compatible with Tr. 


¢ If the method invocation includes explicit type arguments, and the member is a 
generic method, then the number of type arguments is equal to the number of 
type parameters of the method. 


This clause implies that a non-generic method may be potentially applicable to an 
invocation that supplies explicit type arguments. Indeed, it may turn out to be applicable. 
In such a case, the type arguments will simply be ignored. 


This rule stems from issues of compatibility and principles of substitutability. Since 
interfaces or superclasses may be generified independently of their subtypes, we may 
override a generic method with a non-generic one. However, the overriding (non- 
generic) method must be applicable to calls to the generic method, including calls that 


15.12 


539 


15.12 


540 


Method Invocation Expressions EXPRESSIONS 


explicitly pass type arguments. Otherwise the subtype would not be substitutable for its 
generified supertype. 


If the search does not yield at least one method that is potentially applicable, then 
a compile-time error occurs. 


An expression is potentially compatible with a target type according to the 
following rules: 


¢ A lambda expression ($15.27) is potentially compatible with a functional 
interface type 7 (§9.8) if all of the following are true: 


— The arity of the function type of r(§9.9) is the same as the arity of the lambda 
expression. 


— If the function type of 7 has a void return, then the lambda body is either a 
statement expression (§14.8) or a void-compatible block (§15.27.2). 


— If the function type of r has a (non-void) return type, then the lambda body is 
either an expression or a value-compatible block ($15.27.2). 


e A method reference expression ($15.13) is potentially compatible with a 
functional interface type 7 if, where the arity of the function type of r is n, 
there exists at least one potentially applicable method when the method reference 
expression targets the function type with arity n (§15.13.1), and one of the 
following is true: 


— The method reference expression has the form ReferenceType 
[TypeArguments] Identifier and at least one potentially applicable method is 
either (i) static and supports arity n, or (ii) not static and supports arity n-1. 


— The method reference expression has some other form and at least one 
potentially applicable method is not static. 


¢ A lambda expression or a method reference expression is potentially compatible 
with a type variable if the type variable is a type parameter of the candidate 
method. 


¢ A parenthesized expression (§15.8.5) is potentially compatible with a type if its 
contained expression is potentially compatible with that type. 


¢ A conditional expression ($15.25) is potentially compatible with a type if each 
of its second and third operand expressions are potentially compatible with that 
type. 


e A class instance creation expression, a method invocation expression, or an 
expression of a standalone form (§15.2) is potentially compatible with any type. 
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The definition of potential applicability goes beyond a basic arity check to also take 
into account the presence and "shape" of functional interface target types. In some cases 
involving type argument inference, a lambda expression appearing as a method invocation 
argument cannot be properly typed until after overload resolution. These rules allow the 
form of the lambda expression to still be taken into account, discarding obviously incorrect 
target types that might otherwise cause ambiguity errors. 


15.12.2.2 Phase 1: Identify Matching Arity Methods Applicable by Strict 


Invocation 


An argument expression is considered pertinent to applicability for a potentially 
applicable method m unless it has one of the following forms: 


An implicitly typed lambda expression (§15.27.1). 
An inexact method reference expression ($15.13.1). 


If mis a generic method and the method invocation does not provide explicit type 
arguments, an explicitly typed lambda expression or an exact method reference 
expression for which the corresponding target type (as derived from the signature 
of m) is a type parameter of m. 


An explicitly typed lambda expression whose body is an expression that is not 
pertinent to applicability. 


An explicitly typed lambda expression whose body is a block, where at least one 
result expression is not pertinent to applicability. 


A parenthesized expression (§15.8.5) whose contained expression is not 
pertinent to applicability. 


A conditional expression (§ 15.25) whose second or third operand is not pertinent 
to applicability. 


Let m be a potentially applicable method (§15.12.2.1) with arity n and formal 
parameter types F, ... F,, and let e;, ..., e, be the actual argument expressions of 
the method invocation. Then: 


If mis a generic method and the method invocation does not provide explicit type 
arguments, then the applicability of the method is inferred as specified in §18.5.1. 


If m is a generic method and the method invocation provides explicit type 
arguments, then let R; ... Rp (p 2 1) be the type parameters of m, let B, be the 
declared bound of Rk; (1 </ <p), and let uw, ..., up be the explicit type arguments 
given in the method invocation. Then mis applicable by strict invocation if both 
of the following are true: 
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— For 1 si<n, if e; is pertinent to applicability then e; is compatible in a strict 
invocation context with F;[R,!=Uj, ..., Rp!=Up] (§5.3). 


— For 1 </<p, u; <: By[Ri!=U), ..., Rp!=Up). 


¢ If mis not a generic method, then mis applicable by strict invocation if, for 1 < 
i <n, either e; is compatible in a strict invocation context with Fr; (§5.3) or e; 
is not pertinent to applicability. 


If no method applicable by strict invocation is found, the search for applicable 
methods continues with phase 2 (§15.12.2.3). 


Otherwise, the most specific method (§15.12.2.5) is chosen among the methods 
that are applicable by strict invocation. 


The meaning of an implicitly typed lambda expression or an inexact method reference 
expression is sufficiently vague prior to resolving a target type that arguments containing 
these expressions are not considered pertinent to applicability, they are simply ignored 
(except for their expected arity) until overload resolution is finished. 


15.12.2.3. Phase 2: Identify Matching Arity Methods Applicable by Loose 
Invocation 


Let m be a potentially applicable method (§15.12.2.1) with arity n and formal 
parameter types Fy, ..., Fn, and let e;, ..., e, be the actual argument expressions of 
the method invocation. Then: 


¢ If mis a generic method and the method invocation does not provide explicit type 
arguments, then the applicability of the method is inferred as specified in §18.5.1. 


¢ If m is a generic method and the method invocation provides explicit type 
arguments, then let R; ... Rp (p 2 1) be the type parameters of m, let B, be the 
declared bound of Rk; (1 </ <p), and let vu; ... u, be the explicit type arguments 
given in the method invocation. Then mis applicable by loose invocation if both 
of the following are true: 


— For 1 Si<n, if e; is pertinent to applicability ($15.12.2.2) then e; is compatible 
in a loose invocation context with F;[R,!=Uj, ..., Rp!=Up] ($5.3). 


— For1</<p, vu) <: By[Ri!=U), ..., Rp!=Up). 


¢ If mis not a generic method, then mis applicable by loose invocation if, for 1 < 
i <n, either e; is compatible in a loose invocation context with Fr, (§5.3) or e; 
is not pertinent to applicability. 


If no method applicable by loose invocation is found, the search for applicable 
methods continues with phase 3 (§15.12.2.4). 
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Otherwise, the most specific method (§15.12.2.5) is chosen among the methods 
that are applicable by loose invocation. 


15.12.2.4 Phase 3: Identify Methods Applicable by Variable Arity Invocation 


Where a variable arity method has formal parameter types Fy, ..., Fn-1, Fn[], let the 
i'th variable arity parameter type of the method be defined as follows: 


¢ For i<n-1, the i'th variable arity parameter type is F;. 
¢ For i2n, the i'th variable arity parameter type is F,. 


Let mbe a potentially applicable method (§15.12.2.1) with variable arity, let 7, ..., 
T, be the first k variable arity parameter types of m, and let e;, ..., e, be the actual 
argument expressions of the method invocation. Then: 


¢ If mis a generic method and the method invocation does not provide explicit type 
arguments, then the applicability of the method is inferred as specified in §18.5.1. 


¢ If m is a generic method and the method invocation provides explicit type 
arguments, then let R; ... Rp (p 2 1) be the type parameters of m, let B, be the 
declared bound of rR; (1 </ <p), and let vu; ... u, be the explicit type arguments 
given in the method invocation. Then mis applicable by variable arity invocation 
if: 
— For 1 <i<k, if e; is pertinent to applicability (§15.12.2.2) then e; is compatible 
in a loose invocation context with 1; [R,!=Uj, ..., Rp!=Up] ($5.3). 


— For 1 </<p, uv; <: By[Ry!=U), ..., Rp!=Up). 


If mis not a generic method, then mis applicable by variable arity invocation if, 
for 1 <i<k, either e; is compatible in a loose invocation context with T; (§5.3) 
or e; is not pertinent to applicability. 


If no method applicable by variable arity invocation is found, then a compile-time 
error occurs. 


Otherwise, the most specific method (§15.12.2.5) is chosen among the methods 
applicable by variable arity invocation. 


15.12.2.5 Choosing the Most Specific Method 


If more than one member method is both accessible and applicable to a method 
invocation, it is necessary to choose one to provide the descriptor for the run- 
time method dispatch. The Java programming language uses the rule that the most 
specific method is chosen. 
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The informal intuition is that one method is more specific than another if any 
invocation handled by the first method could be passed on to the other one without 
a compile-time error. In cases such as an explicitly typed lambda expression 
argument (§15.27.1) or a variable arity invocation (§15.12.2.4), some flexibility is 
allowed to adapt one signature to the other. 


One applicable method m, is more specific than another applicable method mp, for 
an invocation with argument expressions ey, ..., ex, if any of the following are true: 


* mz iS generic, and m, is inferred to be more specific than m, for argument 
expressions ej, ..., ex by §18.5.4. 


* m2 is not generic, and m, and m; are applicable by strict or loose invocation, and 
where m, has formal parameter types sj, ..., S, and mz has formal parameter types 
T1, «> Tp, the type s; is more specific than T; for argument e; for alli(1 <i< 
n,n=k). 


* m2 is not generic, and m; and mz are applicable by variable arity invocation, and 
where the first k variable arity parameter types of m; are Sj, ..., S;, and the first k 
variable arity parameter types of mz are Tj, ..., T;, the type s; is more specific than 
T; for argument e; for alli (1 <i<k). Additionally, if mz has k+1 parameters, then 
the k+/'th variable arity parameter type of m; is a subtype of the k+/'th variable 
arity parameter type of m2. 


The above conditions are the only circumstances under which one method may be 
more specific than another. 


A type sis more specific than a type T for any expression if s <: T ($4.10). 


A functional interface type sis more specific than a functional interface type 7 for 
an expression e if all of the following are true: 


¢ The interface of s is neither a superinterface nor a subinterface of the interface 
of T. 


If s or ris an intersection type, it is not the case that any interface of s is a 
superinterface or a subinterface of any interface of 7. (The "interfaces of” an 
intersection type refers here to the set of interfaces that appear as (possibly 
parameterized) interface types in the intersection.) 


¢ Let mur, be the function type of the capture of s, and let wr; be the function type 
of T. mT; and mr; must have the same type parameters (if any) (§8.4.4). 


¢ Let P;, ..., Pn, be the formal parameter types of urs, adapted to the type parameters 
of wry. Let P;', ..., P,' be the formal parameter types of the function type of s 
(without capture), adapted to the type parameters of mT. Let Q, ..., Qn be the 
formal parameter types of mr,;. Then, for alli (1 <i<7n), 0; <: P; and OQ; = P;’. 
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Generally, this rule asserts that the formal parameter types derived from s and T are the 
same. But in the case in which s is a wildcard-parameterized type, the check is more 
complex in order to allow capture variables to occur in formal parameter types: first, each 
formal parameter type of T must be a subtype of the corresponding formal parameter 
type of the capture of s; second, after mapping the wildcards to their bounds (§9.9), the 
formal parameter types of the resulting function types are the same. 


¢ Let R, be the return type of urs, adapted to the type parameters of mrz, and let Rr 
be the return type of ur;. One of the following must be true: 


— eis an explicitly typed lambda expression (§15.27.1), and one of the following 
is true: 


> 


> 


> 


Rr 1S void. 
Rg <: Rr. 


Rs and R, are functional interface types, and there is at least one result 
expression, and Rg is more specific than R; for each result expression of e. 


The result expression of a lambda expression with a block body is defined 
in §15.27.2; the result expression of a lambda expression with an expression 
body is simply the body itself. 


Rg iS a primitive type, and R; is a reference type, and there is at least one 
result expression, and each result expression of e is a standalone expression 
($15.2) of a primitive type. 


Rs is areference type, and Rris a primitive type, and there is at least one result 
expression, and each result expression of e is either a standalone expression 
of a reference type or a poly expression. 


— eis an exact method reference expression (§15.13.1), and one of the following 
is true: 


> 


> 


> 


Rr 1S void. 
Rg <: Rr. 


Rg iS aprimitive type, Rris areference type, and the compile-time declaration 
for the method reference has a return type which is a primitive type. 


Rg is areference type, Rris a primitive type, and the compile-time declaration 
for the method reference has a return type which is a reference type. 


— eis aparenthesized expression, and one of these conditions applies recursively 
to the contained expression. 
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— eis a conditional expression, and, for each of the second and third operands, 
one of these conditions applies recursively. 


A method m; is strictly more specific than another method m, if and only if m; is 
more specific than mz and mz is not more specific than m. 


A method is said to be maximally specific for a method invocation if it is accessible 
and applicable and there is no other method that is accessible and applicable that 
is strictly more specific. 


If there is exactly one maximally specific method, then that method is in fact 
the most specific method; it is necessarily more specific than any other accessible 
method that is applicable. It is then subjected to some further compile-time checks 
as specified in §15.12.3. 


It is possible that no method is the most specific, because there are two or more 
methods that are maximally specific. In this case: 


e If all the maximally specific methods have override-equivalent signatures 
(§8.4.2), and exactly one of the maximally specific methods is concrete (that is, 
neither abstract nor default), then it is the most specific method. 


¢ Otherwise, if all the maximally specific methods have override-equivalent 
signatures, and all the maximally specific methods are abstract or default, 
and the declarations of these methods have the same erased parameter types, 
and at least one maximally specific method is preferred according to the rules 
below, then the most specific method is chosen arbitrarily among the subset of 
the maximally specific methods that are preferred. The most specific method is 
then considered to be abstract. 


A maximally specific method is preferred if it has: 


—a signature that is a subsignature of every maximally specific method's 
signature; and 


— areturn type R (possibly void), where either Ris the same as every maximally 
specific method's return type, or R is a reference type and is a subtype of 
every maximally specific method's return type (after adapting for any type 
parameters (§8.4.4) if the two methods have the same signature). 


If no preferred method exists according to the above rules, then a maximally 
specific method is preferred if it: 


— has a signature that is a subsignature of every maximally specific method's 
signature; and 


— is return-type-substitutable (§$8.4.5) for every maximally specific method. 
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The thrown exception types of the most specific method are derived from the 
throws Clauses of the maximally specific methods, as follows: 


1. 


If the most specific method is generic, the throws clauses are first adapted 
to the type parameters of the most specific method (§8.4.4). 


If the most specific method is not generic but at least one maximally specific 
method is generic, the throws clauses are first erased. 


Then, the thrown exception types include every type £ which satisfies the 
following constraints: 


— Eis mentioned in one of the throws clauses. 


— For each throws clause, £ is a subtype of some type named in that clause. 


These rules for deriving a single method type from a group of overloaded methods are 
also used to identify the function type of a functional interface (§9.9). 


¢ Otherwise, the method invocation is ambiguous, and a compile-time error occurs. 


15.12.2.6 Method Invocation Type 


The invocation type of a most specific accessible and applicable method is a method 
type (§8.2) which expresses the target types of the invocation arguments, the result 
(return type or void) of the invocation, and the exception types of the invocation. 
It is determined as follows: 


¢ If the chosen method is generic and the method invocation does not provide 
explicit type arguments, the invocation type is inferred as specified in §18.5.2. 


In this case, if the method invocation expression is a poly expression, then its 
compatibility with a target type is as determined by §18.5.2.1. 


Testing for compatibility with a target type may occur multiple times before making 
a final determination of the method invocation expression's target type and invocation 
type. For example, an enclosing method invocation expression may require testing the 
deeper method invocation expression for compatibility with different methods' formal 
parameter types. 


¢ If the chosen method is generic and the method invocation provides explicit type 
arguments, let P; be the type parameters of the method and let rT; be the explicit 
type arguments provided for the method invocation (1 <i <p). Then: 


— If unchecked conversion was necessary for the method to be applicable, then 


the invocation type's parameter types are obtained by applying the substitution 
[Py=T1, .... Ppt=Tp] to the parameter types of the method's type, and the 
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invocation type's return type and thrown types are given by the erasure of the 
return type and thrown types of the method's type. 


— If unchecked conversion was not necessary for the method to be applicable, 
then the invocation type is obtained by applying the substitution [P;:=7;, ..., 
Pp:=Tp] to the method's type. 


¢ If the chosen method is not generic, then: 


— If unchecked conversion was necessary for the method to be applicable, the 
parameter types of the invocation type are the parameter types of the method's 
type, and the return type and thrown types are given by the erasures of the 
return type and thrown types of the method's type. 


— Otherwise, if the chosen method is the getClass method of the class object 
($4.3.2), the invocation type is the same as the method's type, except that the 
return type is Class<? extends |7|>, where Tis the type that was searched, as 
determined by §15.12.1, and |z| denotes the erasure of r (§4.6). 


— Otherwise, the invocation type is the same as the method's type. 


15.12.3 Compile-Time Step 3: Is the Chosen Method Appropriate? 


If there is a most specific method declaration for a method invocation, it is called 
the compile-time declaration for the method invocation. 


It is a compile-time error if an argument to a method invocation is not compatible 
with its target type, as derived from the invocation type of the compile-time 
declaration. 


If the compile-time declaration is applicable by variable arity invocation, then 
where the last formal parameter type of the invocation type of the method is F,[1, 
it is a compile-time error if the type which is the erasure of F,, is not accessible 
($6.6) at the point of invocation. 


If the compile-time declaration is void, then the method invocation must be a top 
level expression (that is, the Expression in an expression statement or in the ForInit 
or ForUpdate part of a for statement), or a compile-time error occurs. Such a 
method invocation produces no value and so must be used only in a situation where 
a value is not needed. 


In addition, whether the compile-time declaration is appropriate may depend on the 
form of the method invocation expression before the left parenthesis, as follows: 


¢ If the form is MethodName - that is, just an Identifier - and the compile-time 
declaration is an instance method, then: 
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— It is a compile-time error if the method invocation occurs in a static context 
(§8.1.3). 


— Otherwise, let c be the immediately enclosing class of which the compile-time 
declaration is a member. If the method invocation is not directly enclosed by 
c or an inner class of c, then a compile-time error occurs. 


¢ If the form is TypeName . [TypeArguments] Identifier, then the compile-time 
declaration must be static, or a compile-time error occurs. 


e If the form is ExpressionName . [TypeArguments] Identifier or Primary . 
[TypeArguments] Identifier, then the compile-time declaration must not be a 
static method declared in an interface, or a compile-time error occurs. 


¢ If the form is super . [TypeArguments] Identifier, then: 

— It is a compile-time error if the compile-time declaration is abstract. 

— It is a compile-time error if the method invocation occurs in a static context. 
¢ If the form is TypeName . super . [TypeArguments] Identifier, then: 

— It is a compile-time error if the compile-time declaration is abstract. 

— It is a compile-time error if the method invocation occurs in a static context. 


— If TypeName denotes a class c, then if the method invocation is not directly 
enclosed by c or an inner class of c, a compile-time error occurs. 


— If TypeName denotes an interface, let r be the type declaration immediately 
enclosing the method invocation. A compile-time error occurs if there exists a 
method, distinct from the compile-time declaration, that overrides (§9.4.1) the 
compile-time declaration from a direct superclass or direct superinterface of T. 


In the case that a superinterface overrides a method declared in a grandparent 
interface, this rule prevents the child interface from "skipping" the override by simply 
adding the grandparent to its list of direct superinterfaces. The appropriate way to 
access functionality of a grandparent is through the direct superinterface, and only if 
that interface chooses to expose the desired behavior. (Alternately, the programmer 
is free to define an additional superinterface that exposes the desired behavior with 
a super method invocation.) 


The compile-time parameter types and compile-time result are determined as 
follows: 


¢ If the compile-time declaration for the method invocation is not a signature 
polymorphic method, then: 
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— The compile-time parameter types are the types of the formal parameters of 
the compile-time declaration. 


— The compile-time result is the result of the invocation type of the compile- 
time declaration (§15.12.2.6). 


¢ If the compile-time declaration for the method invocation is a signature 
polymorphic method, then: 


— The compile-time parameter types are the types of the actual argument 
expressions. An argument expression which is the null literal nu11 (§3.10.7) 
is treated as having the type void. 


— The compile-time result is determined as follows: 


>» Ifthe signature polymorphic method is either void or has a return type other 
than object, the compile-time result is the result of the invocation type of 
the compile-time declaration (§15.12.2.6). 


>» Otherwise, if the method invocation expression is an expression statement, 
the compile-time result is void. 


» Otherwise, if the method invocation expression is the operand of a cast 
expression ($15.16), the compile-time result is the erasure of the type of the 
cast expression (§4.6). 


>» Otherwise, the compile-time result is the signature polymorphic method's 
return type, Object. 


A method is signature polymorphic if all of the following are true: 


e It is declared in the java.lang.invoke.MethodHandle class or the 
java.lang.invoke.VarHandle class. 


¢ It has asingle variable arity parameter (§8.4.1) whose declared type is object []. 
¢ It is native. 


The following compile-time information is then associated with the method 
invocation for use at run time: 


¢ The name of the method. 

¢ The qualifying type of the method invocation (§13.1). 

¢ The number of parameters and the compile-time parameter types, in order. 
¢ The compile-time result. 


¢ The invocation mode, computed as follows: 
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— If the compile-time declaration has the static modifier, then the invocation 
mode is static. 


— Otherwise, if the part of the method invocation before the left parenthesis is 
of the form super . Identifier or of the form TypeName . super . Identifier, 
then the invocation mode is super. 


— Otherwise, if the qualifying type of the method invocation is an interface, then 
the invocation mode is interface. 


— Otherwise, the invocation mode is virtual. 


If the result of the invocation type of the compile-time declaration is not void, 
then the type of the method invocation expression is obtained by applying capture 
conversion (§5.1.10) to the return type of the invocation type of the compile-time 
declaration. 


15.12.4 Run-Time Evaluation of Method Invocation 


At run time, method invocation requires five steps. First, a target reference may be 
computed. Second, the argument expressions are evaluated. Third, the accessibility 
of the method to be invoked is checked. Fourth, the actual code for the method to 
be executed is located. Fifth, a new activation frame is created, synchronization is 
performed if necessary, and control is transferred to the method code. 


15.12.4.1 Compute Target Reference (If Necessary) 
There are six cases to consider, depending on the form of the method invocation: 
¢ If the form is MethodName - that is, just an Identifier - then: 

— If the invocation mode is static, then there is no target reference. 


— Otherwise, let r be the enclosing type declaration of which the method is a 
member, and let be an integer such that rT is the n'th lexically enclosing type 
declaration of the class whose declaration immediately contains the method 
invocation. The target reference is the n'th lexically enclosing instance of this. 


It is a compile-time error if the n'th lexically enclosing instance of this does 
not exist. 


¢ If the form is TypeName . [TypeArguments] Identifier, then there is no target 
reference. 


¢ If form is ExpressionName . [TypeArguments] Identifier, then: 
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— If the invocation mode is static, then there is no target reference. The 
ExpressionName is evaluated, but the result is then discarded. 


— Otherwise, the target reference is the value denoted by ExpressionName. 
¢ If the form is Primary . [TypeArguments] Identifier involved, then: 


— Ifthe invocation mode is st atic, then there is no target reference. The Primary 
expression is evaluated, but the result is then discarded. 


— Otherwise, the Primary expression is evaluated and the result is used as the 
target reference. 


In either case, if the evaluation of the Primary expression completes abruptly, 
then no part of any argument expression appears to have been evaluated, and the 
method invocation completes abruptly for the same reason. 


¢ If the form is super . [TypeArguments] Identifier, then the target reference is 
the value of this. 


e If the form is TypeName . super . [TypeArguments] Identifier, then if 
TypeName denotes a class, the target reference is the value of TypeName .this; 
otherwise, the target reference is the value of this. 


Example 15.12.4.1-1. Target References and st atic Methods 


When a target reference is computed and then discarded because the invocation mode is 
static, the reference is not examined to see whether it is nul 1: 


class Testl { 
static void mountain() { 
System.out.printin ("Monadnock") ; 


static Testl favorite() { 
System.out.print ("Mount "); 
return null; 


public static void main(String[] args) { 
favorite() .mountain(); 


} 
which prints: 
Mount Monadnock 


Here favorite () returns null, yet no NullPointerException is thrown. 
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Example 15.12.4.1-2. Evaluation Order During Method Invocation 


As part of an instance method invocation (§15.12), there is an expression that denotes the 
object to be invoked. This expression appears to be fully evaluated before any part of any 
argument expression to the method invocation is evaluated. 


So, for example, in: 


class Test2 { 
public static void main(String[] args) { 
String s = "one"; 
if (s.startsWith(s = "two") ) 
System.out.println ("oops") ; 


the occurrence of s before ".startsWith" is evaluated first, before the argument 
expression s = "two". Therefore, a reference to the string "one" is remembered as the 
target reference before the local variable s is changed to refer to the string "two". As a 
result, the start sWith method is invoked for target object "one" with argument "two", 
so the result of the invocation is false, as the string "one" does not start with "two". It 
follows that the test program does not print "oops". 


15.12.4.2 Evaluate Arguments 


The process of evaluating the argument list differs, depending on whether the 
method being invoked is a fixed arity method or a variable arity method (§8.4.1). 


If the method being invoked is a variable arity method m, it necessarily has n > 0 
formal parameters. The final formal parameter of m necessarily has type T[] for 
some T, and mis necessarily being invoked with k = 0 actual argument expressions. 


If mis being invoked with k # n actual argument expressions, or, if m is being 
invoked with k =n actual argument expressions and the type of the é'th argument 
expression is not assignment compatible with r[], then the argument list (e, ..., 
Cn-1y Cns «+5 €x) iS evaluated as if it were written as (e:, ..., en-1, new |TE]| { ens. 
ex }), where |T[1| denotes the erasure (§4.6) of T[1. 


The preceding paragraph is crafted to handle the interaction of parameterized types and 
array types that occurs in a Java Virtual Machine with erased generics. Namely, if the 
element type T of the variable array parameter is non-reifiable, e.g. List<String>, then 
special care must be taken with the array creation expression (§ 15.10) because the created 
array's element type must be reifiable. By erasing the array type of the final expression 
in the argument list, we are guaranteed to obtain a reifiable element type. Then, since the 
array creation expression appears in an invocation context (§5.3), an unchecked conversion 
is possible from the array type with reifiable element type to an array type with non- 
reifiable element type, specifically that of the variable arity parameter. A Java compiler is 
required to give a compile-time unchecked warning at this conversion. Oracle's reference 
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implementation of a Java compiler identifies this unchecked warning as a more informative 
unchecked generic array creation. 


The argument expressions (possibly rewritten as described above) are now 
evaluated to yield argument values. Each argument value corresponds to exactly 
one of the method's n formal parameters. 


The argument expressions, if any, are evaluated in order, from left to right. If the 
evaluation of any argument expression completes abruptly, then no part of any 
argument expression to its right appears to have been evaluated, and the method 
invocation completes abruptly for the same reason. The result of evaluating the 
j'th argument expression is the j'th argument value, for 1 <j <n. Evaluation then 
continues, using the argument values, as described below. 


15.12.4.3. Check Accessibility of Type and Method 

In this section: 

¢ Let p be the class containing the method invocation. 

¢ Let r be the qualifying type of the method invocation (§13.1). 

¢ Let mbe the name of the method as determined at compile time (§15.12.3). 


An implementation of the Java programming language must ensure, as part of 
linkage, that the type rT is accessible: 


¢ If ris in the same package as p, then ris accessible. 


¢ If ris in a different package than p, and their packages are in the same module, 
and Tis public or protected, then T is accessible. 


¢ If ris ina different package than p, and their packages are in different modules, 
and T's module exports 7's package to p's module, and Tis public or protected, 
then ris accessible. 


If Tis protected, it is necessarily a nested type, so at compile time, its accessibility is 
affected by the accessibility of types enclosing its declaration. However, during linkage, its 
accessibility is not affected by the accessibility of types enclosing its declaration. Moreover, 
during linkage, aprotected Tis as accessible as a public T. These discrepancies between 
access control at compile time (§6.6) and access control at run time are due to limitations 
in the Java Virtual Machine. 


The implementation must also ensure, during linkage, that the method mcan still 
be found in 7 or a supertype of r. If m cannot be found, then a NoSuchMethodError 
(which is a subclass of IncompatibleClassChangeError) occurs. If m can be 
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found, then let c be the type that declares m. The implementation must ensure, 
during linkage, that the declaration of min cis accessible to p: 


e If mis public, then mis accessible. 


¢ If mis protected, then mis accessible iff (i) either D is in the same package as 
c, or Dis asubtype of cor citself; and (ii) if mis a protected instance method, 
then 7 must be a subtype of p or p itself. 


This is the only place where Tis involved in checks for m, because a protected instance 
method may only be invoked via a qualifying type that aligns with the invoker's type. 


¢ If mhas package access, then mis accessible iff D is in the same package as c. 


¢ If mis private, then mis accessible iff Dis c, or p encloses c, or c encloses pD, 
or cand pare both enclosed by a third type. 


If either 7 or mis not accessible, then an IllegalAccessError occurs (§12.3). 


If the invocation mode is interface, then the implementation must check 
that the target reference type still implements the specified interface. If 
the target reference type does not still implement the interface, then an 


IncompatibleClassChangeError OCCUIS. 


15.12.4.4 Locate Method to Invoke 
As in the previous section (§15.12.4.3): 
¢ Let r be the qualifying type of the method invocation (§13.1). 


¢ Let mbe the method found in r or a supertype of r. (Note that m was merely the 
name of the method in the previous section; here it is the actual declaration.) 


¢ Let c be the class or interface that declares m. 
The strategy for locating a method to invoke depends on the invocation mode: 


¢ If the invocation mode is static, no target reference is needed and overriding 
is not allowed. Method m of class or interface cis the one to be invoked. 


¢ Otherwise, an instance method is to be invoked and there is a target reference. 
If the target reference is null, a Nul1lPointerException is thrown at this point. 
Otherwise, the target reference is said to refer to a target object and will be 
used as the value of the keyword this in the invoked method. The other three 
possibilities for the invocation mode are then considered: 
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— If the invocation mode is super, overriding is not allowed. Method m 
of class or interface c is the one to be invoked. If m is abstract, an 
AbstractMethodError is thrown. 


— Otherwise, if the invocation mode is virtual, and fT and m jointly indicate a 
signature polymorphic method (§15.12.3), then the target object is an instance 
of java.lang.invoke.MethodHandle Or java.lang.invoke.VarHandle. 
The target object encapsulates state which is matched against the information 
associated with the method invocation at compile time. Details of this 
matching are given in The Java Virtual Machine Specification, Java SE 
12 Edition and the Java SE Platform API. If matching succeeds, then 
either the method referenced by the java.lang.invoke.MethodHandle 
instance is directly and immediately invoked, or the variable represented 
by the java.lang.invoke.VarHandle instance is directly and immediately 
accessed, and in either case the procedure in §15.12.4.5 is not executed. 
If matching fails, then a java.lang. invoke.WrongMethodTypeException is 
thrown. 


— Otherwise, the invocation mode is interface Or virtual. 


If the method m of class or interface cis private, then it is the method to be 
invoked. 


Otherwise, overriding may occur. A dynamic method lookup, specified below, 
is used to locate the method to invoke. The lookup procedure starts from class 
R, the actual run-time class of the target object. 


Note that for invocation mode interface, R necessarily implements 1; for 
invocation mode virtual, R is necessarily either T or a subclass of T. If the target 
object is an array, then Ris a "class" representing an array type. 
The procedure for dynamic method lookup is as follows. Let s be the class to search, 
beginning with r. Then: 


1. Ifclass s contains a declaration for a method that overrides method m of class 
or interface c from R (§8.4.8.1), then that overriding method is the method to 
be invoked, and the procedure terminates. 


2. Otherwise, if s has a superclass, then steps 1 and 2 of this lookup procedure 
are performed recursively using the direct superclass of s in place of s; the 
method to be invoked, if any, is the result of the recursive invocation of this 
lookup procedure. 


3. If no method is found by the previous two steps, the superinterfaces of s are 
searched for a suitable method. 
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A set of candidate methods is considered with the following properties: (i) 
each method is declared in a (direct or indirect) superinterface of R; (ii) each 
method has the name and descriptor required by the method invocation; (iii) 
each method is non-static and non-private; (iv) for each method, where the 
method's declaring interface is 1, there is no other method satisfying (i) through 
(iii) that is declared in a subinterface of r. 


If this set contains a default method, one such method is the method to be 
invoked. Otherwise, an abstract method in the set is selected as the method 
to be invoked. 


Dynamic method lookup may cause the following errors to occur: 


If the method to be invoked is abstract, an AbstractMethodError 1s thrown. 


If the method to be invoked is default, and more than one 
default method appears in the set of candidates in step 3 above, an 
IncompatibleClassChangeError is thrown. 


If the invocation mode is interface and the method to be invoked is neither 
public nor private, an IllegalAccessError is thrown. 


The above procedure (if it terminates without error) will find a non-abstract, 
accessible method to invoke, provided that all classes and interfaces in the program 
have been consistently compiled. However, if this is not the case, then various 
errors may occur, as specified above; additional details about the behavior of the 
Java Virtual Machine under these circumstances are given by The Java Virtual 
Machine Specification, Java SE 12 Edition. 


The dynamic lookup process, while described here explicitly, will often be implemented 
implicitly, for example as a side-effect of the construction and use of per-class method 
dispatch tables, or the construction of other per-class structures used for efficient dispatch. 


Example 15.12.4.4-1. Overriding and Method Invocation 


class Point { 
final int EDGE = 20; 
int x, y; 
void move(int dx, int dy) { 
x += dx; y += dy; 
if (Math.abs(x) >= EDGE || Math.abs(y) >= EDGE) 
clear(); 
} 
void clear() { 
System.out.printin("\tPoint clear"); 
x = 0; y = 0; 
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class ColoredPoint extends Point { 
int color; 
void clear() { 
System.out.printin("\tColoredPoint clear"); 
super.clear(); 
color = 0; 


Here, the subclass ColoredPoint extends the clear abstraction defined by its superclass 
Point. It does so by overriding the clear method with its own method, which invokes the 
clear method of its superclass, using the form super.clear (). 


This method is then invoked whenever the target object for an invocation of clear is 
a ColoredPoint. Even the method move in Point invokes the clear method of class 
ColoredPoint when the class of this is ColoredPoint, as shown by the output of this 
test program: 


class Testl { 
public static void main(String[] args) { 
Point p = new Point(); 
System.out.println("p.move(20,20):"); 
p-move (20, 20); 


ColoredPoint cp = new ColoredPoint (); 
System.out.printin("cp.move (20,20) :"); 
cp.move (20, 20); 


p = new ColoredPoint (); 
System.out.printin("p.move (20,20), p colored:"); 
p-move (20, 20); 


which is: 


p-move (20,20): 
Point clear 

cp.move (20,20): 
ColoredPoint clear 
Point clear 

p-move (20,20), p colored: 
ColoredPoint clear 
Point clear 


Overriding is sometimes called "late-bound self-reference"; in this example it means that 
the reference to clear in the body of Point .move (which is really syntactic shorthand for 
this.clear) invokes a method chosen "late" (at run time, based on the run-time class of 
the object referenced by this) rather than a method chosen "early" (at compile time, based 
only on the type of this). This provides the programmer a powerful way of extending 
abstractions and is a key idea in object-oriented programming. 
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Example 15.12.4.4-2. Method Invocation Using super 


An overridden instance method of a superclass may be accessed by using the keyword 
super to access the members of the immediate superclass, bypassing any overriding 
declaration in the class that contains the method invocation. 


When accessing an instance variable, super means the same as a cast of this (§15.11.2), 
but this equivalence does not hold true for method invocation. This is demonstrated by the 
example: 


class Tl { 
String s() { return "1"; } 
} 
class T2 extends Tl { 
String s() { return "2"; } 
} 
class T3 extends T2 { 
String s() { return "3"; } 
void test() { 


System.out.printin("s()=\t\t" + s()); 
System.out.printin("super.s()=\t" + super.s()); 
System.out.println("((T2)this).s()=\t" + ((T2)this).s()); 
System.out.println("((T1)this).s()=\t" + ((T1)this).s()); 


} 
} 
class Test2 { 
public static void main(String[] args) { 
T3 t3 = new T3(); 
t3.test(); 


which produces the output: 


s()= 2 
super.s()= 2 
((T2)this).s()= 3 
((T1)this).s()= 3 


The casts to types T1 and T2 do not change the method that is invoked, because the instance 
method to be invoked is chosen according to the run-time class of the object referred to 
by this. A cast does not change the class of an object; it only checks that the class is 
compatible with the specified type. 


15.12.4.5 Create Frame, Synchronize, Transfer Control 
A method min some class s has been identified as the one to be invoked. 


Now a new activation frame is created, containing the target reference (if any) and 
the argument values (if any), as well as enough space for the local variables and 
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stack for the method to be invoked and any other bookkeeping information that may 
be required by the implementation (stack pointer, program counter, reference to 
previous activation frame, and the like). If there is not sufficient memory available 
to create such an activation frame, a StackOverflowError is thrown. 


The newly created activation frame becomes the current activation frame. The 
effect of this is to assign the argument values to corresponding freshly created 
parameter variables of the method, and to make the target reference available as 
this, if there is a target reference. Before each argument value is assigned to its 
corresponding parameter variable, it is subjected to invocation conversion ($5.3), 
which includes any required value set conversion (§5.1.13). 


If the erasure ($4.6) of the type of the method being invoked differs in its signature 
from the erasure of the type of the compile-time declaration for the method 
invocation (§15.12.3), then if any of the argument values is an object which is not 
an instance of a subclass or subinterface of the erasure of the corresponding formal 
parameter type in the compile-time declaration for the method invocation, then a 
ClassCastException 1s thrown. 


If the method m is a native method but the necessary native, implementation- 
dependent binary code has not been loaded or otherwise cannot be dynamically 
linked, then an UnsatisfiedLinkError is thrown. 


If the method m is not synchronized, control is transferred to the body of the 
method m to be invoked. 


If the method mis synchronized, then an object must be locked before the transfer 
of control. No further progress can be made until the current thread can obtain 
the lock. If there is a target reference, then the target object must be locked; 
otherwise the class object for class s, the class of the method m, must be locked. 
Control is then transferred to the body of the method m to be invoked. The object is 
automatically unlocked when execution of the body of the method has completed, 
whether normally or abruptly. The locking and unlocking behavior is exactly as if 
the body of the method were embedded in a synchronized statement ($14.19). 


Example 15.12.4.5-1. Invoked Method Signature Has Different Erasure Than Compile- 
Time Method Signature 


Consider the declarations: 


abstract class C<T> { 
abstract T id(T x); 
} 
class D extends C<String> { 
String id(String x) { return x; } 


} 
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Now, given an invocation: 


C c = new D(); 
c.id(new Object()); // fails with a ClassCastException 


The erasure of the actual method being invoked, D.id(), differs in its signature from that 
of the compile-time method declaration, c.id(). The former takes an argument of type 
String while the latter takes an argument of type Object. The invocation fails with a 
ClassCastException before the body of the method is executed. 


Such situations can only arise if the program gives rise to a compile-time unchecked 
warning (§4.8, §5.1.6, §5.1.9, §8.4.1, §8.4.8.3, §15.13.2, §15.12.4.2, §15.27.3). 


Implementations can enforce these semantics by creating bridge methods. In the above 
example, the following bridge method would be created in class D: 


Object id(Object x) { return id((String) x); } 


This is the method that would actually be invoked by the Java Virtual Machine in response 
to the call c.id(new Object ()) shown above, and it will execute the cast and fail, as 
required. 


15.13. Method Reference Expressions 


A method reference expression is used to refer to the invocation of a method 
without actually performing the invocation. Certain forms of method reference 
expression also allow class instance creation ($15.9) or array creation (§15.10) to 
be treated as if it were a method invocation. 


MethodReference: 
ExpressionName :: [TypeArguments] Identifier 
Primary :: [TypeArguments] Identifier 
ReferenceType :: [TypeArguments] Identifier 
super :: [TypeArguments] Identifier 
TypeName . super :: [TypeArguments] Identifier 
ClassType :: [TypeArguments] new 
ArrayType :: new 


If TypeArguments is present to the right of : :, then it is a compile-time error if any 
of the type arguments are wildcards (§4.5.1). 


If a method reference expression has the form ExpressionName 
[TypeArguments] Identifier or Primary :: [TypeArguments] Identifier, it is a 
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compile-time error if the type of the ExpressionName or Primary is not a reference 
type. 


If a method reference expression has the form super :: /[TypeArguments] 
Identifier, let T be the type declaration immediately enclosing the method reference 
expression. It is a compile-time error if ris the class Object or T is an interface. 


If a method reference expression has the form TypeName . super 
[TypeArguments] Identifier, then: 


¢ If TypeName denotes a class, c, then it is a compile-time error if cis not a lexically 
enclosing class of the current class, or if cis the class object. 


¢ If TypeName denotes an interface, z, then let r be the type declaration 
immediately enclosing the method reference expression. It is a compile-time 
error if I is not a direct superinterface of r, or if there exists some other direct 
superclass or direct superinterface of r, 7, such that 7is a subtype of 1. 


¢ If TypeName denotes a type variable, then a compile-time error occurs. 


If a method reference expression has the form super : : [TypeArguments] Identifier 
or TypeName . super :: [TypeArguments] Identifier, it is a compile-time error if 
the expression occurs in a static context. 


If a method reference expression has the form ClassType : : [TypeArguments] new, 
then: 


¢ ClassType must denote a class that is accessible (§6.6), non-abstract, and not 
an enum type, or a compile-time error occurs. 


¢ If ClassType denotes a parameterized type (§4.5), then it is a compile-time error 
if any of its type arguments are wildcards. 


¢ If ClassType denotes a raw type (§4.8), then it is a compile-time error if 
TypeArguments is present after the : :. 


If a method reference expression has the form ArrayType :: new, then ArrayType 
must denote a type that is reifiable ($4.7), or a compile-time error occurs. 


The target reference of an instance method (§15.12.4.1) may be provided by the 
method reference expression using an ExpressionName, a Primary, or super, Or 
it may be provided later when the method is invoked. The immediately enclosing 
instance of a new inner class instance (§15.9.2) is provided by a lexically enclosing 
instance of this (§8.1.3). 


When more than one member method of a type has the same name, or when a class 
has more than one constructor, the appropriate method or constructor is selected 
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based on the functional interface type targeted by the method reference expression, 
as specified in §15.13.1. 


If a method or constructor is generic, the appropriate type arguments may either 
be inferred or provided explicitly. Similarly, the type arguments of a generic 
type mentioned by the method reference expression may be provided explicitly or 
inferred. 


Method reference expressions are always poly expressions ($15.2). 


It is a compile-time error if a method reference expression occurs in a program in 
someplace other than an assignment context (§5.2), an invocation context (§5.3), 
or a casting context (§5.5). 


Evaluation of a method reference expression produces an instance of a functional 
interface type ($9.8). This does not cause the execution of the corresponding 
method; instead, the execution may occur at a later time when an appropriate 
method of the functional interface is invoked. 


Here are some method reference expressions, first with no target reference and then with 
a target reference: 


String::length // instance method 
System::currentTimeMillis // static method 

List<String>::size // explicit type arguments for generic type 
List::size // inferred type arguments for generic type 
int[]::clone 

T::tvarMember 


System.out::println 

"abc"::length 

foo[x]::bar 

(test ? list.replaceAll(String::trim) : list) :: iterator 
super: :toString 


Here are some more method reference expressions: 


String: :valueOf // overload resolution needed 
Arrays::sort // type arguments inferred from context 
Arrays::<String>sort // explicit type arguments 


Here are some method reference expressions that represent a deferred creation of an object 
or an atray: 
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ArrayList<String>::new // constructor for parameterized type 
ArrayList: :new // inferred type arguments 

// for generic class 
Foo: :<Integer>new // explicit type arguments 


// for generic constructor 
Bar<String>::<Integer>new // generic class, generic constructor 
Outer.Inner: :new // inner class constructor 
int[]::new // array creation 


It is not possible to specify a particular signature to be matched, for example, 
Arrays::sort (int[]). Instead, the functional interface provides argument types that 
are used as input to the overload resolution algorithm (§15.12.2). This should satisfy the 
vast majority of use cases; when the rare need arises for more precise control, a lambda 
expression can be used. 


The use of type argument syntax in the class name before a _ delimiter 
(List<String>::size) raises the parsing problem of distinguishing between < as a type 
argument bracket and < as a less-than operator. In theory, this is no worse than allowing 
type arguments in cast expressions; however, the difference is that the cast case only comes 
up when a ( token is encountered; with the addition of method reference expressions, the 
start of every expression is potentially a parameterized type. 


15.13.1 Compile-Time Declaration of a Method Reference 


The compile-time declaration of a method reference expression is the method to 
which the expression refers. In special cases, the compile-time declaration does not 
actually exist, but is a notional method that represents a class instance creation or 
an array creation. The choice of compile-time declaration depends on a function 
type targeted by the expression, just as the compile-time declaration of a method 
invocation depends on the invocation's arguments (§15.12.3). 


The search for a compile-time declaration mirrors the process for method 
invocations in §15.12.1 and §15.12.2, as follows: 


¢ First, a type to search is determined: 


— If the method reference expression has the form ExpressionName 
[TypeArguments] Identifier or Primary :: [TypeArguments] Identifier, the 
type to search is the type of the expression preceding the : : token. 


—If the method reference expression has the form ReferenceType 
[TypeArguments] Identifier, the type to search is the result of capture 
conversion (§5.1.10) applied to ReferenceType. 


— If the method reference expression has the form super :: [TypeArguments] 
Identifier, the type to search is the superclass type of the class whose 
declaration contains the method reference. 
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— If the method reference expression has the form TypeName . super :: 
[TypeArguments] Identifier, then if TypeName denotes a class, the type to 
search is the superclass type of the named class; otherwise, TypeName denotes 
an interface, and the corresponding superinterface type of the class or interface 
whose declaration contains the method reference is the type to search. 


— For the two other forms (involving : : new), the referenced method is notional 
and there is no type to search. 


¢ Second, given a targeted function type with n parameters, a set of potentially 
applicable methods is identified: 


—If the method reference expression has the form ReferenceType 
[TypeArguments] Identifier, then the potentially applicable methods are: 


>» the member methods of the type to search that would be potentially 
applicable (§15.12.2.1) for a method invocation which names /dentifier, has 
arity n, has type arguments TypeArguments, and appears in the same class 
as the method reference expression; plus 


>» the member methods of the type to search that would be potentially 
applicable for a method invocation which names Identifier, has arity n-1, 
has type arguments TypeArguments, and appears in the same class as the 
method reference expression. 


Two different arities, n and n-1, are considered, to account for the possibility that this 
form refers to either a static method or an instance method. 


—If the method reference expression has the form ClassType 
[TypeArguments] new, then the potentially applicable methods are a set of 
notional methods corresponding to the constructors of ClassType. 


If ClassType is a raw type, but is not a non-stat ic member type of a raw type, 
the candidate notional member methods are those specified in §15.9.3 for a 
class instance creation expression that uses <> to elide the type arguments to a 
class. Otherwise, the candidate notional member methods are the constructors 
of ClassType, treated as if they were methods with return type ClassType. 


Among these candidates, the potentially applicable methods are the notional 
methods that would be potentially applicable for a method invocation which 
has arity n, has type arguments TypeArguments, and appears in the same class 
as the method reference expression. 


— If the method reference expression has the form ArrayType :: new, a single 
notional method is considered. The method has a single parameter of type int, 
returns the ArrayType, and has no throws clause. If n = 1, this is the only 
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potentially applicable method; otherwise, there are no potentially applicable 
methods. 


— For all other forms, the potentially applicable methods are the member 
methods of the type to search that would be potentially applicable for a 
method invocation which names /dentifier, has arity n, has type argument 
TypeArguments, and appears in the same class as the method reference 
expression. 


Finally, if there are no potentially applicable methods, then there is no compile- 
time declaration. 


Otherwise, given a targeted function type with parameter types P;, ..., P, anda 
set of potentially applicable methods, the compile-time declaration is selected 
as follows: 


—If the method reference expression has the form ReferenceType 
[TypeArguments] Identifier, then two searches for a most specific applicable 
method are performed. Each search is as specified in $15.12.2.2 through 
§15.12.2.5, with the clarifications below. Each search produces a set of 
applicable methods and, possibly, designates a most specific method of the set. 
In the case of an error as specified in §15.12.2.4, the set of applicable methods 
is empty. In the case of an error as specified in §15.12.2.5, there is no most 
specific method. 


In the first search, the method reference is treated as if it were an invocation 
with argument expressions of types P;, ..., P,. Type arguments, if any, are given 
by the method reference expression. 


In the second search, if P;, ..., Py, is not empty and Pp, is a subtype of 
ReferenceType, then the method reference expression is treated as if it were 
a method invocation expression with argument expressions of types Py, ..., 
P,. If ReferenceType is a raw type, and there exists a parameterization of this 
type, G<...>, that is a supertype of P;, the type to search is the result of capture 
conversion (§5.1.10) applied to c<...>; otherwise, the type to search is the same 
as the type of the first search. Type arguments, if any, are given by the method 
reference expression. 


If the first search produces a most specific method that is static, and the set 
of applicable methods produced by the second search contains no non-static 
methods, then the compile-time declaration is the most specified method of 
the first search. 


Otherwise, if the set of applicable methods produced by the first search 
contains no static methods, and the second search produces a most specific 
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method that is non-static, then the compile-time declaration is the most 
specific method of the second search. 


Otherwise, there is no compile-time declaration. 


— For all other forms of method reference expression, one search for a most 
specific applicable method is performed. The search is as specified in 
§15.12.2.2 through §15.12.2.5, with the clarifications below. 


The method reference is treated as if it were an invocation with argument 
expressions of types P, ..., Pn; the type arguments, if any, are given by the 
method reference expression. 


If the search results in an error as specified in §15.12.2.2 through §15.12.2.5, 
or if the most specific applicable method is static, there is no compile-time 
declaration. 


Otherwise, the compile-time declaration is the most specific applicable 
method. 


It is a compile-time error if a method reference expression has the form 
ReferenceType : : [TypeArguments] Identifier, and the compile-time declaration is 
static, and ReferenceType is not a simple or qualified name (§6.2). 


It is a compile-time error if the method reference expression has the form super : : 
[TypeArguments] Identifier or TypeName . super :: [TypeArguments] Identifier, 
and the compile-time declaration is abstract. 


It is a compile-time error if the method reference expression has the form 
TypeName . super :: [TypeArguments] Identifier, and TypeName denotes an 
interface, and there exists a method, distinct from the compile-time declaration, 
that overrides (§8.4.8, §9.4.1) the compile-time declaration from a direct superclass 
or direct superinterface of the type whose declaration immediately encloses the 
method reference expression. 


It is a compile-time error if the method reference expression is of the form 
ClassType :: [TypeArguments] new and a compile-time error would occur when 
determining an enclosing instance for ClassType as specified in §15.9.2 (treating 
the method reference expression as if it were an unqualified class instance creation 
expression). 


A method reference expression of the form ReferenceType : : [TypeArguments] Identifier 
can be interpreted in different ways. If /dentifier refers to an instance method, then the 
implicit lambda expression has an extra parameter compared to if Identifier refers to a 
static method. It is possible for ReferenceType to have both kinds of applicable methods, 
so the search algorithm described above identifies them separately, since there are different 
parameter types for each case. 
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An example of ambiguity is: 


interface Fun<T,R> { R apply(T arg); } 


class C { 
int size() { return 0; } 
static int size(Object arg) { return 0; } 


void test() { 
Fun<C, Integer> fl = C::size; 
// Error: instance method size() 
// or static method size (Object) ? 


This ambiguity cannot be resolved by providing an applicable instance method which is 
more specific than an applicable static method: 


interface Fun<T,R> { R apply(T arg); } 


class C { 
int size() { return 0; } 
static int size(Object arg) { return 0; } 
int size(C arg) { return 0; } 


void test() { 
Fun<C, Integer> fl = C::size; 
// Error: instance method size() 
// or static method size (Object) ? 


The search is smart enough to ignore ambiguities in which all the applicable methods (from 
both searches) are instance methods: 


interface Fun<T,R> { R apply(T arg); } 


class C { 
int size() { return 0; } 
int size(Object arg) { return 0; } 
int size(C arg) { return 0; } 


void test() { 
Fun<C, Integer> fl = C::size; 
// OK: reference is to instance method size() 


For convenience, when the name of a generic type is used to refer to an instance 
method (where the receiver becomes the first parameter), the target type is used to 
determine the type arguments. This facilitates usage like Pair::first in place of 
Pair<String, Integer>::first. Similarly, a method reference like Pair: :new is 
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treated like a "diamond" instance creation (new Pair<>()). Because the "diamond" is 
implicit, this form does not instantiate a raw type; in fact, there is no way to express a 
reference to the constructor of a raw type. 


For some method reference expressions, there is only one possible compile-time 
declaration with only one possible invocation type (§15.12.2.6), regardless of the 
targeted function type. Such method reference expressions are said to be exact. A 
method reference expression that is not exact is said to be inexact. 


A method reference expression ending with /dentifier is exact if it satisfies all of 
the following: 


e If the method reference expression has the form ReferenceType 
[TypeArguments] Identifier, then ReferenceType does not denote a raw type. 


¢ The type to search has exactly one member method with the name /dentifier that 
is accessible to the class or interface in which the method reference expression 
appears. 


¢ This method is not variable arity (§8.4.1). 


¢ If this method is generic (§8.4.4), then the method reference expression provides 
TypeArguments. 


A method reference expression of the form ClassType :: [TypeArguments] new is 
exact if it satisfies all of the following: 


¢ The type denoted by ClassType is not raw, or is a non-static member type of 
a raw type. 


¢ The type denoted by ClassType has exactly one constructor that is accessible to 
the class or interface in which the method reference expression appears. 


¢ This constructor is not variable arity. 


¢ If this constructor is generic, then the method reference expression provides 
TypeArguments. 


A method reference expression of the form ArrayType :: new is always exact. 


15.13.2 Type of a Method Reference 


A method reference expression is compatible in an assignment context, invocation 
context, or casting context with a target type 7 if T is a functional interface type 
($9.8) and the expression is congruent with the function type of the ground target 
type derived from T. 


The ground target type is derived from rT as follows: 
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¢ If ris a wildcard-parameterized functional interface type, then the ground target 
type is the non-wildcard parameterization (§9.9) of rT. 


¢ Otherwise, the ground target type is T. 


A method reference expression is congruent with a function type if both of the 
following are true: 


¢ The function type identifies a single compile-time declaration corresponding to 
the reference. 


¢ One of the following is true: 
— The result of the function type is void. 


— The result of the function type is R, and the result of applying capture 
conversion (§5.1.10) to the return type of the invocation type (§15.12.2.6) of 
the chosen compile-time declaration is R' (where R is the target type that may 
be used to infer rR’), and neither R nor R' is void, and R' is compatible with Rr 
in an assignment context. 


If unchecked conversion was necessary for the compile-time declaration to be 
applicable, and this conversion would cause an unchecked warning in an invocation 
context, then a compile-time unchecked warning occurs, unless suppressed by 
@SuppressWarnings (§9.6.4.5). 


Ifunchecked conversion was necessary for the return type Rr’, described above, to be 
compatible with the function type's return type, R, and this conversion would cause 
an unchecked warning in an assignment context, then a compile-time unchecked 
warning occurs, unless suppressed by @SuppressWarnings. 


If a method reference expression is compatible with a target type r, then the type 
of the expression, u, is the ground target type derived from rT. 


It is a compile-time error if any class or interface mentioned by either vu or the 
function type of vis not accessible ($6.6) from the class or interface in which the 
method reference expression appears. 


For each non-static member method m of u, if the function type of u has a 
subsignature of the signature of m, then a notional method whose method type is the 
function type of u is said to override m, and any compile-time error or unchecked 
warning specified in §8.4.8.3 may occur. 


For each checked exception type x listed in the throws clause of the invocation 
type of the compile-time declaration, x or a superclass of x must be mentioned in 
the throws clause of the function type of u, or a compile-time error occurs. 
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The key idea driving the compatibility definition is that a method reference is compatible if 
and only if the equivalent lambda expression (x, y, z) -> exp.<Tl, T2>method (x, 
y, z) 1s compatible. (This is informal, and there are issues that make it difficult or 
impossible to formally define the semantics in terms of such a rewrite.) 


These compatibility rules provide a convenient facility for converting from one functional 
interface to another: 


Task t = () -> System.out.printlin("hi") ; 
Runnable r = t::invoke; 


The implementation may be optimized so that when a lambda-derived object is passed 
around and converted to various types, this does not result in many levels of adaptation 
logic around the core lambda body. 


Unlike a lambda expression, a method reference can be congruent with a generic function 
type (that is, a function type that has type parameters). This is because the lambda 
expression would need to be able to declare type parameters, and no syntax supports this; 
while for a method reference, no such declaration is necessary. For example, the following 
program is legal: 


interface ListFactory { 
<T> List<T> make(); 


} 


ListFactory lf = ArrayList: :new; 
List<String> ls = lf.make(); 
List<Number> In = 1lf.make(); 


15.13.3. Run-Time Evaluation of Method References 


At run time, evaluation of a method reference expression is similar to evaluation 
of a class instance creation expression, insofar as normal completion produces a 
reference to an object. Evaluation of a method reference expression is distinct from 
invocation of the method itself. 


First, if the method reference expression begins with an ExpressionName or a 
Primary, this subexpression is evaluated. If the subexpression evaluates to null, a 
NullPointerException is raised, and the method reference expression completes 
abruptly. If the subexpression completes abruptly, the method reference expression 
completes abruptly for the same reason. 


Next, either a new instance of a class with the properties below is allocated and 
initialized, or an existing instance of a class with the properties below is referenced. 
If a new instance is to be created, but there is insufficient space to allocate 
the object, evaluation of the method reference expression completes abruptly by 
throwing an OutOfMemoryError. 
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The value of a method reference expression is a reference to an instance of a class 
with the following properties: 


The class implements the targeted functional interface type and, if the target type 
is an intersection type, every other interface type mentioned in the intersection. 


Where the method reference expression has type vu, for each non-st at ic member 
method m of u: 


If the function type of u has a subsignature of the signature of m, then the class 
declares an invocation method that overrides m. The invocation method's body 
invokes the referenced method, creates a class instance, or creates an array, as 
described below. If the invocation method's result is not void, then the body 
returns the result of the method invocation or object creation, after any necessary 
assignment conversions (§5.2). 


If the erasure of the type of a method being overridden differs in its signature 
from the erasure of the function type of u, then before the method invocation or 
object creation, an invocation method's body checks that each argument value 
is an instance of a subclass or subinterface of the erasure of the corresponding 
parameter type in the function type of u; if not, acClassCastException is thrown. 


The class overrides no other methods of the functional interface type or other 
interface types mentioned above, although it may override methods of the object 
class. 


The body of an invocation method depends on the form of the method reference 
expression, as follows: 


If the form is ExpressionName :: [TypeArguments] Identifier or Primary :: 
[TypeArguments] Identifier, then the body of the invocation method has the 
effect of a method invocation expression for a compile-time declaration which 
is the compile-time declaration of the method reference expression. Run-time 
evaluation of the method invocation expression is as specified in §15.12.4.3, 
§15.12.4.4, and §15.12.4.5, where: 


— The invocation mode is derived from the compile-time declaration as specified 
in §15.12.3. 


— The target reference is the value of ExpressionName or Primary, as determined 
when the method reference expression was evaluated. 


— The arguments to the method invocation expression are the formal parameters 
of the invocation method. 


If the form is ReferenceType :: [TypeArguments] Identifier, the body of the 
invocation method similarly has the effect of a method invocation expression for 
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a compile-time declaration which is the compile-time declaration of the method 
reference expression. Run-time evaluation of the method invocation expression 
is as specified in §15.12.4.3, §15.12.4.4, and §15.12.4.5, where: 


— The invocation mode is derived from the compile-time declaration as specified 
in §15.12.3. 


— If the compile-time declaration is an instance method, then the target reference 
is the first formal parameter of the invocation method. Otherwise, there is no 
target reference. 


— If the compile-time declaration is an instance method, then the arguments 
to the method invocation expression (if any) are the second and subsequent 
formal parameters of the invocation method. Otherwise, the arguments to the 
method invocation expression are the formal parameters of the invocation 
method. 


¢ If the form is super :: [TypeArguments] Identifier or TypeName . super :: 
[TypeArguments] Identifier, the body of the invocation method has the effect 
of a method invocation expression for a compile-time declaration which is 
the compile-time declaration of the method reference expression. Run-time 
evaluation of the method invocation expression is as specified in §15.12.4.3, 
§15.12.4.4, and §15.12.4.5, where: 


— The invocation mode is super. 


— If the method reference expression begins with a TypeName that names a class, 
the target reference is the value of TypeName . this at the point at which the 
method reference is evaluated. Otherwise, the target reference is the value of 
this at the point at which the method reference is evaluated. 


— The arguments to the method invocation expression are the formal parameters 
of the invocation method. 


¢ If the form is ClassType :: [TypeArguments] new, the body of the invocation 
method has the effect of a class instance creation expression of the form new 
[TypeArguments] ClassType(A, ..., An), Where the arguments a), ..., A, are the 
formal parameters of the invocation method, and where: 


— The enclosing instance for the new object, if any, is derived from the site of 
the method reference expression, as specified in §15.9.2. 


— The constructor to invoke is the constructor that corresponds to the compile- 
time declaration of the method reference (§15.13.1). 


¢ If the form is Type ca :: new (k 2 1), then the body of the invocation method 
has the same effect as an array creation expression of the form new Type [ size ] 
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ce , where size is the invocation method's single parameter. (The notation [] 


indicates a sequence of k bracket pairs.) 


k 


If the body of the invocation method has the effect of a method invocation 
expression, then the compile-time parameter types and the compile-time result of 
the method invocation are determined as specified in §15.12.3. For the purpose 
of determining the compile-time result, the method invocation expression is an 
expression statement if the invocation method's result is void, and the Expression 
of a return statement if the invocation method's result is non-void. 


The timing of method reference expression evaluation is more complex than that of lambda 
expressions (§15.27.4). When a method reference expression has an expression (rather than 
a type) preceding the : : separator, that subexpression is evaluated immediately. The result 
of evaluation is stored until the method of the corresponding functional interface type is 
invoked; at that point, the result is used as the target reference for the invocation. This means 
the expression preceding the : : separator is evaluated only when the program encounters 
the method reference expression, and is not re-evaluated on subsequent invocations on the 
functional interface type. 


It is interesting to contrast the treatment of null here with its treatment during method 
invocation. When a method invocation expression is evaluated, itis possible for the Primary 
that qualifies the invocation to evaluate to null but for no Nul1lPointerException to 
be raised. This occurs when the invoked method is static (despite the syntax of the 
invocation suggesting an instance method). Since the applicable method for a method 
reference expression qualified by a Primary is prohibited from being static (§15.13.1), 
the evaluation of the method reference expression is simpler - anu11 Primary always raises 
aNullPointerException. 


15.14 Postfix Expressions 


Postfix expressions include uses of the postfix ++ and -- operators. Names are not 
considered to be primary expressions ($15.8), but are handled separately in the 
grammar to avoid certain ambiguities. They become interchangeable only here, at 
the level of precedence of postfix expressions. 


PostfixExpression: 
Primary 
ExpressionName 
PostIncrementExpression 
PostDecrementExpression 
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15.14.1 Expression Names 


The rules for evaluating expression names are given in §6.5.6. 


15.14.2 Postfix Increment Operator ++ 


A postfix expression followed by a ++ operator is a postfix increment expression. 


PostIncrementExpression: 
PostfixExpression ++ 


The result of the postfix expression must be a variable of a type that is convertible 
($5.1.8) to a numeric type, or a compile-time error occurs. 


The type of the postfix increment expression is the type of the variable. The result 
of the postfix increment expression is not a variable, but a value. 


At run time, if evaluation of the operand expression completes abruptly, then 
the postfix increment expression completes abruptly for the same reason and no 
incrementation occurs. Otherwise, the value 1 is added to the value of the variable 
and the sum is stored back into the variable. Before the addition, binary numeric 
promotion (§5.6.2) is performed on the value 1 and the value of the variable. If 
necessary, the sum is narrowed by a narrowing primitive conversion (§5.1.3) and/ 
or subjected to boxing conversion (§5.1.7) to the type of the variable before it is 
stored. The value of the postfix increment expression is the value of the variable 
before the new value is stored. 


Note that the binary numeric promotion mentioned above may include unboxing conversion 
(§5.1.8) and value set conversion (§5.1.13). If necessary, value set conversion is applied to 
the sum prior to its being stored in the variable. 


A variable that is declared final cannot be incremented because when an access of 
such a final variable is used as an expression, the result is a value, not a variable. 
Thus, it cannot be used as the operand of a postfix increment operator. 


15.14.3 Postfix Decrement Operator -- 


A postfix expression followed by a -- operator is a postfix decrement expression. 


PostDecrementExpression: 
PostfixExpression -- 
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The result of the postfix expression must be a variable of a type that is convertible 
($5.1.8) to a numeric type, or a compile-time error occurs. 


The type of the postfix decrement expression is the type of the variable. The result 
of the postfix decrement expression is not a variable, but a value. 


At run time, if evaluation of the operand expression completes abruptly, then 
the postfix decrement expression completes abruptly for the same reason and no 
decrementation occurs. Otherwise, the value 1 is subtracted from the value of the 
variable and the difference is stored back into the variable. Before the subtraction, 
binary numeric promotion (§5.6.2) is performed on the value 1 and the value of 
the variable. If necessary, the difference is narrowed by a narrowing primitive 
conversion (§5.1.3) and/or subjected to boxing conversion (§5.1.7) to the type of 
the variable before it is stored. The value of the postfix decrement expression is the 
value of the variable before the new value is stored. 


Note that the binary numeric promotion mentioned above may include unboxing conversion 
(§5.1.8) and value set conversion (§5.1.13). If necessary, value set conversion is applied to 
the difference prior to its being stored in the variable. 


A variable that is declared final cannot be decremented because when an access of 
such a final variable is used as an expression, the result is a value, not a variable. 
Thus, it cannot be used as the operand of a postfix decrement operator. 


15.15 Unary Operators 


The operators +, -, ++, --, ~, !, and the cast operator (§15.16) are called the unary 
operators. 
UnaryExpression: 


PreIncrementExpression 
PreDecrementExpression 

+ UnaryExpression 

- UnaryExpression 
UnaryExpressionNotPlusMinus 


PreIncrementExpression: 
++ UnaryExpression 


PreDecrementExpression: 
-- UnaryExpression 
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UnaryExpressionNotPlusMinus: 
PostfixExpression 
~ UnaryExpression 
! UnaryExpression 
CastExpression 


The following production from §15.16 is shown here for convenience: 


CastExpression: 
( PrimitiveType ) UnaryExpression 
( ReferenceType {AdditionalBound} ) UnaryExpressionNotPlusMinus 
( ReferenceType {AdditionalBound} ) LambdaExpression 


Expressions with unary operators group right-to-left, so that -~x means the same 
as -—(~x). 


This portion of the grammar contains some tricks to avoid two potential syntactic 
ambiguities. 


The first potential ambiguity would arise in expressions such as (p) +q, which looks, to a 
C or C++ programmer, as though it could be either a cast to type p of a unary + operating 
on q, or a binary addition of two quantities p and q. In C and C++, the parser handles this 
problem by performing a limited amount of semantic analysis as it parses, so that it knows 
whether p is the name of a type or the name of a variable. 


Java takes a different approach. The result of the + operator must be numeric, and all 
type names involved in casts on numeric values are known keywords. Thus, if p is 
a keyword naming a primitive type, then (p)+q can make sense only as a cast of a 
unary expression. However, if p is not a keyword naming a primitive type, then (p) +q 
can make sense only as a binary arithmetic operation. Similar remarks apply to the 
— operator. The grammar shown above splits CastExpression into two cases to make 
this distinction. The nonterminal UnaryExpression includes all unary operators, but the 
nonterminal UnaryExpressionNotPlusMinus excludes uses of all unary operators that could 
also be binary operators, which in Java are + and -. 


The second potential ambiguity is that the expression (p)++ could, to a C or C++ 
programmer, appear to be either a postfix increment of a parenthesized expression or the 
beginning of a cast, for example, in (p)++q. As before, parsers for C and C++ know 
whether p is the name of a type or the name of a variable. But a parser using only one-token 
lookahead and no semantic analysis during the parse would not be able to tell, when ++ is 
the lookahead token, whether (p) should be considered a Primary expression or left alone 
for later consideration as part of a CastExpression. 


In Java, the result of the ++ operator must be numeric, and all type names involved in casts 
on numeric values are known keywords. Thus, if p is a keyword naming a primitive type, 
then (p) ++ can make sense only as a cast of a prefix increment expression, and there had 
better be an operand such as q following the ++. However, if p is not a keyword naming a 
primitive type, then (p) ++ can make sense only as a postfix increment of p. Similar remarks 
apply to the -- operator. The nonterminal UnaryExpressionNotPlusMinus therefore also 
excludes uses of the prefix operators ++ and --. 


577 


15.15 


578 


Unary Operators EXPRESSIONS 


15.15.1 Prefix Increment Operator ++ 


A unary expression preceded by a ++ operator is a prefix increment expression. 


The result of the unary expression must be a variable of a type that is convertible 
($5.1.8) to a numeric type, or a compile-time error occurs. 


The type of the prefix increment expression is the type of the variable. The result 
of the prefix increment expression is not a variable, but a value. 


At run time, if evaluation of the operand expression completes abruptly, then 
the prefix increment expression completes abruptly for the same reason and no 
incrementation occurs. Otherwise, the value 1 is added to the value of the variable 
and the sum is stored back into the variable. Before the addition, binary numeric 
promotion (§5.6.2) is performed on the value 1 and the value of the variable. If 
necessary, the sum is narrowed by a narrowing primitive conversion (§5.1.3) and/ 
or subjected to boxing conversion (§5.1.7) to the type of the variable before it is 
stored. The value of the prefix increment expression is the value of the variable 
after the new value is stored. 


Note that the binary numeric promotion mentioned above may include unboxing conversion 
(§5.1.8) and value set conversion (§5.1.13). If necessary, value set conversion is applied to 
the sum prior to its being stored in the variable. 


A variable that is declared final cannot be incremented because when an access of 
such a final variable is used as an expression, the result is a value, not a variable. 
Thus, it cannot be used as the operand of a prefix increment operator. 


15.15.2 Prefix Decrement Operator -- 
A unary expression preceded by a -- operator is a prefix decrement expression. 


The result of the unary expression must be a variable of a type that is convertible 
($5.1.8) to a numeric type, or a compile-time error occurs. 


The type of the prefix decrement expression is the type of the variable. The result 
of the prefix decrement expression is not a variable, but a value. 


At run time, if evaluation of the operand expression completes abruptly, then 
the prefix decrement expression completes abruptly for the same reason and no 
decrementation occurs. Otherwise, the value 1 is subtracted from the value of the 
variable and the difference is stored back into the variable. Before the subtraction, 
binary numeric promotion (§5.6.2) is performed on the value 1 and the value of 
the variable. If necessary, the difference is narrowed by a narrowing primitive 
conversion (§5.1.3) and/or subjected to boxing conversion (§5.1.7) to the type of 
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the variable before it is stored. The value of the prefix decrement expression is the 
value of the variable after the new value is stored. 


Note that the binary numeric promotion mentioned above may include unboxing conversion 
(§5.1.8) and value set conversion (§5.1.13). If necessary, format conversion is applied to 
the difference prior to its being stored in the variable. 


A variable that is declared final cannot be decremented because when an access of 
such a final variable is used as an expression, the result is a value, not a variable. 
Thus, it cannot be used as the operand of a prefix decrement operator. 


15.15.3. Unary Plus Operator + 


The type of the operand expression of the unary + operator must be a type that is 
convertible (§5.1.8) to a primitive numeric type, or a compile-time error occurs. 


Unary numeric promotion (§5.6.1) is performed on the operand. The type of the 
unary plus expression is the promoted type of the operand. The result of the unary 
plus expression is not a variable, but a value, even if the result of the operand 
expression is a variable. 


At run time, the value of the unary plus expression is the promoted value of the 
operand. 


15.15.4 Unary Minus Operator - 


The type of the operand expression of the unary - operator must be a type that is 
convertible (§5.1.8) to a primitive numeric type, or a compile-time error occurs. 


Unary numeric promotion (§5.6.1) is performed on the operand. 
The type of the unary minus expression is the promoted type of the operand. 


Note that unary numeric promotion performs value set conversion (§5.1.13). 
Whatever value set the promoted operand value is drawn from, the unary negation 
operation is carried out and the result is drawn from that same value set. That result 
is then subject to further value set conversion. 


At run time, the value of the unary minus expression is the arithmetic negation of 
the promoted value of the operand. 


For integer values, negation is the same as subtraction from zero. The Java 
programming language uses two's-complement representation for integers, and the 
range of two's-complement values is not symmetric, so negation of the maximum 
negative int or long results in that same maximum negative number. Overflow 
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occurs in this case, but no exception is thrown. For all integer values x, -x equals 
(~x) +1. 


For floating-point values, negation is not the same as subtraction from zero, because 
if x is +0.0, then 0.0-x is +0.0, but -x is -0.0. Unary minus merely inverts the 
sign of a floating-point number. Special cases of interest: 


¢ If the operand is NaN, the result is NaN. (Recall that NaN has no sign (§4.2.3).) 
¢ If the operand is an infinity, the result is the infinity of opposite sign. 


e If the operand is a zero, the result is the zero of opposite sign. 


15.15.5 Bitwise Complement Operator ~ 


The type of the operand expression of the unary ~ operator must be a type that is 
convertible (§5.1.8) to a primitive integral type, or a compile-time error occurs. 


Unary numeric promotion (§5.6.1) is performed on the operand. The type of the 
unary bitwise complement expression is the promoted type of the operand. 


At run time, the value of the unary bitwise complement expression is the bitwise 
complement of the promoted value of the operand. In all cases, ~x equals (-x) -1. 


15.15.6 Logical Complement Operator ! 


The type of the operand expression of the unary ! operator must be boolean or 
Boolean, or a compile-time error occurs. 


The type of the unary logical complement expression is boolean. 


At run time, the operand is subject to unboxing conversion (§5.1.8) if necessary. 
The value of the unary logical complement expression is true if the (possibly 
converted) operand value is false, and false if the (possibly converted) operand 
value is true. 


15.16 Cast Expressions 


A cast expression converts, at run time, a value of one numeric type to a similar 
value of another numeric type; or confirms, at compile time, that the type of an 
expression iS boolean; or checks, at run time, that a reference value refers to an 
object either whose class is compatible with a specified reference type or list of 
reference types, or which embodies a value of a primitive type. 
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CastExpression: 
( PrimitiveType ) UnaryExpression 
( ReferenceType {AdditionalBound} ) UnaryExpressionNotPlusMinus 
( ReferenceType {AdditionalBound} ) LambdaExpression 


The following production from §4.4 is shown here for convenience: 


AdditionalBound: 
& InterfaceType 


The parentheses and the type or list of types they contain are sometimes called the 
cast operator. 


If the cast operator contains a list of types, that is, a ReferenceType followed by 
one or more AdditionalBound terms, then all of the following must be true, or a 
compile-time error occurs: 


¢ ReferenceType must denote a class or interface type. 
¢ The erasures (§4.6) of all the listed types must be pairwise different. 


¢ No two listed types may be subtypes of different parameterizations of the same 
generic interface. 


The target type for the casting context (§5.5) introduced by the cast expression is 
either the PrimitiveType or the ReferenceType (if not followed by AdditionalBound 
terms) appearing in the cast operator, or the intersection type denoted by the 
ReferenceType and AdditionalBound terms appearing in the cast operator. 


The type of a cast expression is the result of applying capture conversion (§5.1.10) 
to this target type. 


Casts can be used to explicitly "tag" a lambda expression or a method reference expression 
with a particular target type. To provide an appropriate degree of flexibility, the target type 
may be a list of types denoting an intersection type, provided the intersection induces a 
functional interface (§9.8). 


The result of a cast expression is not a variable, but a value, even if the result of 
evaluating the operand expression is a variable. 


A cast operator has no effect on the choice of value set (§4.2.3) for a value of type 
float or type double. Consequently, a cast to type float within an expression that 
is not FP-strict ($15.4) does not necessarily cause its value to be converted to an 
element of the float value set, and a cast to type double within an expression that 
is not FP-strict does not necessarily cause its value to be converted to an element 
of the double value set. 
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If the compile-time type of the operand cannot be converted by casting conversion 
($5.5) to the target type specified by the cast operator, then a compile-time error 
occurs. 


Otherwise, at run time, the operand value is converted (if necessary) by casting 
conversion to the target type specified by the cast operator. 


A ClassCastExcept ion is thrown if a cast is found at run time to be impermissible. 


Some casts result in an error at compile time. Some casts can be proven, at compile time, 
always to be correct at run time. For example, it is always correct to convert a value of a 
class type to the type of its superclass; such a cast should require no special action at run 
time. Finally, some casts cannot be proven to be either always correct or always incorrect 
at compile time. Such casts require a test at run time. See §5.5 for details. 


15.17 Multiplicative Operators 


The operators *, /, and % are called the multiplicative operators. 


MultiplicativeExpression: 
UnaryExpression 
MultiplicativeExpression * UnaryExpression 
MultiplicativeExpression / UnaryExpression 
MultiplicativeExpression * UnaryExpression 


The multiplicative operators have the same precedence and are syntactically left- 
associative (they group left-to-right). 


The type of each of the operands of a multiplicative operator must be a type that is 
convertible (§5.1.8) to a primitive numeric type, or a compile-time error occurs. 


Binary numeric promotion is performed on the operands (§5.6.2). 


Note that binary numeric promotion performs value set conversion (§5.1.13) and may 
perform unboxing conversion (§5.1.8). 


The type of a multiplicative expression is the promoted type of its operands. 
If the promoted type is int or long, then integer arithmetic is performed. 


If the promoted type is float or double, then floating-point arithmetic is 
performed. 
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15.17.1 Multiplication Operator * 


The binary * operator performs multiplication, producing the product of its 
operands. 


Multiplication is a commutative operation if the operand expressions have no side 
effects. 


Integer multiplication is associative when the operands are all of the same type. 
Floating-point multiplication is not associative. 


If an integer multiplication overflows, then the result is the low-order bits of the 
mathematical product as represented in some sufficiently large two's-complement 
format. As a result, if overflow occurs, then the sign of the result may not be the 
same as the sign of the mathematical product of the two operand values. 


The result of a floating-point multiplication is determined by the rules of IEEE 754 
arithmetic: 


¢ If either operand is NaN, the result is NaN. 


¢ If the result is not NaN, the sign of the result is positive if both operands have 
the same sign, and negative if the operands have different signs. 


¢ Multiplication of an infinity by a zero results in NaN. 


¢ Multiplication of an infinity by a finite value results in a signed infinity. The sign 
is determined by the rule stated above. 


e In the remaining cases, where neither an infinity nor NaN is involved, the exact 
mathematical product is computed. A floating-point value set is then chosen: 


— If the multiplication expression is FP-strict ($15.4): 


> If the type of the multiplication expression is float, then the float value set 
must be chosen. 


>» If the type of the multiplication expression is double, then the double value 
set must be chosen. 


— If the multiplication expression is not FP-strict: 


>» If the type of the multiplication expression is float, then either the float 
value set or the float-extended-exponent value set may be chosen, at the 
whim of the implementation. 


>» Ifthe type of the multiplication expression is double, then either the double 
value set or the double-extended-exponent value set may be chosen, at the 
whim of the implementation. 
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Next, a value must be chosen from the chosen value set to represent the product. 


If the magnitude of the product is too large to represent, we say the operation 
overflows; the result is then an infinity of appropriate sign. 


Otherwise, the product is rounded to the nearest value in the chosen value 
set using IEEE 754 round-to-nearest mode. The Java programming language 
requires support of gradual underflow as defined by IEEE 754 (§4.2.4). 


Despite the fact that overflow, underflow, or loss of information may occur, 
evaluation of a multiplication operator * never throws a run-time exception. 


15.17.2 Division Operator / 


The binary / operator performs division, producing the quotient of its operands. 
The left-hand operand is the dividend and the right-hand operand is the divisor. 


Integer division rounds toward 0. That is, the quotient produced for operands n and 
d that are integers after binary numeric promotion (§5.6.2) is an integer value q 
whose magnitude is as large as possible while satisfying |d - q| < |n|. Moreover, qg 
is positive when |n| 2 |d| and n and d have the same sign, but g is negative when 
\n| = |d| and n and d have opposite signs. 


There is one special case that does not satisfy this rule: if the dividend is the negative 
integer of largest possible magnitude for its type, and the divisor is -1, then integer 
overflow occurs and the result is equal to the dividend. Despite the overflow, no 
exception is thrown in this case. On the other hand, if the value of the divisor in an 
integer division is 0, then an ArithmeticException is thrown. 


The result of a floating-point division is determined by the rules of IEEE 754 
arithmetic: 


¢ If either operand is NaN, the result is NaN. 


¢ If the result is not NaN, the sign of the result is positive if both operands have 
the same sign, and negative if the operands have different signs. 


¢ Division of an infinity by an infinity results in NaN. 


¢ Division of an infinity by a finite value results in a signed infinity. The sign is 
determined by the rule stated above. 


¢ Division of a finite value by an infinity results in a signed zero. The sign is 
determined by the rule stated above. 


¢ Division of a zero by a zero results in NaN; division of zero by any other finite 
value results in a signed zero. The sign is determined by the rule stated above. 
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¢ Division of a nonzero finite value by a zero results in a signed infinity. The sign 
is determined by the rule stated above. 


e In the remaining cases, where neither an infinity nor NaN is involved, the exact 
mathematical quotient is computed. A floating-point value set is then chosen: 


— If the division expression is FP-strict ($15.4): 


>» If the type of the division expression is float, then the float value set must 
be chosen. 


>» If the type of the division expression is double, then the double value set 
must be chosen. 


— If the division expression is not FP-strict: 


>» If the type of the division expression is float, then either the float value 
set or the float-extended-exponent value set may be chosen, at the whim of 
the implementation. 


>» Ifthe type of the division expression is double, then either the double value 
set or the double-extended-exponent value set may be chosen, at the whim 
of the implementation. 


Next, a value must be chosen from the chosen value set to represent the quotient. 


If the magnitude of the quotient is too large to represent, we say the operation 
overflows; the result is then an infinity of appropriate sign. 


Otherwise, the quotient is rounded to the nearest value in the chosen value 
set using IEEE 754 round-to-nearest mode. The Java programming language 
requires support of gradual underflow as defined by IEEE 754 (§4.2.4). 


Despite the fact that overflow, underflow, division by zero, or loss of information 
may occur, evaluation of a floating-point division operator / never throws a run- 
time exception. 


15.17.3. Remainder Operator « 


The binary % operator is said to yield the remainder of its operands from an implied 
division; the left-hand operand is the dividend and the right-hand operand is the 
divisor. 


In C and C++, the remainder operator accepts only integral operands, but in the 
Java programming language, it also accepts floating-point operands. 


The remainder operation for operands that are integers after binary numeric 
promotion (§5.6.2) produces a result value such that (a/b) *b+(a%b) is equal to a. 
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This identity holds even in the special case that the dividend is the negative integer 
of largest possible magnitude for its type and the divisor is -1 (the remainder is 0). 


It follows from this rule that the result of the remainder operation can be negative 
only if the dividend is negative, and can be positive only if the dividend is positive. 
Moreover, the magnitude of the result is always less than the magnitude of the 
divisor. 


If the value of the divisor for an integer remainder operator is 0, then an 
ArithmeticException is thrown. 


Example 15.17.3-1. Integer Remainder Operator 


class Testl { 
public static void main(String[] args) { 
int a = 5%3; // 2 
int b = 5/3; // 1 
System.out.println("5%3 produces "+ a+ 
"(note that 5/3 produces "+ b+ ")"); 


into 5%(-3); // 2 
int d = 5/(-3); // -1 


System.out.println("5%(-3) produces "+ c+ 
"(note that 5/(-3) produces "+ d+ ")"); 
int e = (-5)%3; // -2 
int £ = (-5)/3; // -1 
System.out.println("(-5)%3 produces "+ e+ 
" (note that (-5)/3 produces "+ £ + ")"); 
int g = (-5)%(-3); // -2 
int h = (-5)/(-3); // 1 
System.out.println("(-5)%(-3) produces "+g + 


"(note that (-5)/(-3) produces "+h + ")"); 


This program produces the output: 


x 
© 


5%33 produces 2 (note that 5/3 produces 1) 

5%(-3) produces 2 (note that 5/(-3) produces -1) 
(-5)%3 produces -2 (note that (-5)/3 produces -1) 
(-5)%(-3) produces -2 (note that (-5)/(-3) produces 1) 


The result of a floating-point remainder operation as computed by the operator 
is not the same as that produced by the remainder operation defined by IEEE 
754. The IEEE 754 remainder operation computes the remainder from a rounding 
division, not a truncating division, and so its behavior is not analogous to that 
of the usual integer remainder operator. Instead, the Java programming language 
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defines % on floating-point operations to behave in a manner analogous to that of 
the integer remainder operator; this may be compared with the C library function 
fmod. The IEEE 754 remainder operation may be computed by the library routine 
Math. IEEEremainder. 


The result of a floating-point remainder operation is determined by the rules of 
IEEE 754 arithmetic: 


¢ If either operand is NaN, the result is NaN. 
¢ If the result is not NaN, the sign of the result equals the sign of the dividend. 
¢ If the dividend is an infinity, or the divisor is a zero, or both, the result is NaN. 


¢ If the dividend is finite and the divisor is an infinity, the result equals the 
dividend. 


¢ If the dividend is a zero and the divisor is finite, the result equals the dividend. 


¢ Inthe remaining cases, where neither an infinity, nor a zero, nor NaN is involved, 
the floating-point remainder r from the division of a dividend n by a divisor d 
is defined by the mathematical relation r = n - (d - g) where gq is an integer that 
is negative only if n/d is negative and positive only if n/d is positive, and whose 
magnitude is as large as possible without exceeding the magnitude of the true 
mathematical quotient of n and d. 


Evaluation of a floating-point remainder operator * never throws a run-time 
exception, even if the right-hand operand is zero. Overflow, underflow, or loss of 
precision cannot occur. 


Example 15.17.3-2. Floating-Point Remainder Operator 


class Test2 
public static void main(String[] args) { 
double a = 5.0%3.0; // 2.0 
System.out.println("5.0%3.0 produces " + a); 


double b = 5.0%(-3.0); // 2.0 
System.out.println("5.0%(-3.0) produces " + b); 


double c = (-5.0)%3.0; // -2.0 
System.out.println("(-5.0)%3.0 produces "+ c); 
double d = (-5.0)%(-3.0); // -2.0 
System.out.println("(-5.0)%(-3.0) produces " + d); 


} 


This program produces the output: 
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0 produces 2.0 

-3.0) produces 2.0 

$3.0 produces -2.0 
(-3.0) produces -2.0 


15.18 Additive Operators 


The operators + and - are called the additive operators. 


AdditiveExpression: 
MultiplicativeExpression 
AdditiveExpression + MultiplicativeExpression 
AdditiveExpression - MultiplicativeExpression 


The additive operators have the same precedence and are syntactically left- 
associative (they group left-to-right). 


If the type of either operand of a + operator is String, then the operation is string 
concatenation. 


Otherwise, the type of each of the operands of the + operator must be a type that is 
convertible (§5.1.8) to a primitive numeric type, or a compile-time error occurs. 


In every case, the type of each of the operands of the binary - operator must be 
a type that is convertible (§5.1.8) to a primitive numeric type, or a compile-time 
error occurs. 


15.18.1 String Concatenation Operator + 


If only one operand expression is of type String, then string conversion (§5.1.11) 
is performed on the other operand to produce a string at run time. 


The result of string concatenation is a reference to a String object that is the 
concatenation of the two operand strings. The characters of the left-hand operand 
precede the characters of the right-hand operand in the newly created string. 


The string object is newly created ($12.5) unless the expression is a constant 
expression ($15.28). 


An implementation may choose to perform conversion and concatenation in one step 
to avoid creating and then discarding an intermediate String object. To increase the 
performance of repeated string concatenation, a Java compiler may use the StringBuffer 
class or a similar technique to reduce the number of intermediate St ring objects that are 
created by evaluation of an expression. 
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For primitive types, an implementation may also optimize away the creation of a wrapper 
object by converting directly from a primitive type to a string. 


Example 15.18.1-1. String Concatenation 
The example expression: 

"The square root of 2 is " + Math.sqrt (2) 
produces the result: 

"The square root of 2 is 1.4142135623730952" 


The + operator is syntactically left-associative, no matter whether it is determined by 
type analysis to represent string concatenation or numeric addition. In some cases care is 
required to get the desired result. For example, the expression: 


at D+ oC 
is always regarded as meaning: 
(a+b) +c 
Therefore the result of the expression: 
1+ 2 + " fiddlers" 
is: 
"3 fiddlers" 
but the result of: 
"fiddlers "+ 1+ 2 
is: 
"fiddlers 12" 
Example 15.18.1-2. String Concatenation and Conditionals 
In this jocular little example: 


class Bottles { 
static void printSong(Object stuff, int n) { 
String plural = (n == 1) ? ™" : "Ss"; 
loop: while (true) { 
System.out.println(n + " bottle" + plural 
+ " of " + stuff + " on the wall,"); 
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System.out.println(n + " bottle" + plural 
aw oP © oe shuth + Neh) y 
System.out.println("You take one down " 
+ "and pass it around:"); 


break loop; 
System.out.println(n + " bottle" + plural 
+ " of " + stuff + " on the wall!"); 
System.out.println(); 
} 
System.out.println("No bottles of " + 
stuff + " on the wall!"); 


public static void main(String[] args) { 
printSong("slime", 3); 


the method print Song will print a version of a children's song. Popular values for stuff 
include "pop" and "beer"; the most popular value for n is 100. Here is the output that 
results from running the program: 


3 bottles of slime on the wall, 
3 bottles of slime; 
You take one down and pass it around: 
2 bottles of slime on the wall! 


2 bottles of slime on the wall, 
2 bottles of slime; 
You take one down and pass it around: 
1 bottle of slime on the wall 


1 bottle of slime on the wall, 
1 bottle of slime; 

You take one down and pass it around: 
No bottles of slime on the wall! 


In the code, note the careful conditional generation of the singular "bottle" when 
appropriate rather than the plural "bottles"; note also how the string concatenation 
operator was used to break the long constant string: 


"You take one down and pass it around:" 


into two pieces to avoid an inconveniently long line in the source code. 
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15.18.2 Additive Operators (+ and -) for Numeric Types 


The binary + operator performs addition when applied to two operands of numeric 
type, producing the sum of the operands. 


The binary - operator performs subtraction, producing the difference of two 
numeric operands. 


Binary numeric promotion is performed on the operands (§5.6.2). 


Note that binary numeric promotion performs value set conversion (§5.1.13) and may 
perform unboxing conversion (§5.1.8). 


The type of an additive expression on numeric operands is the promoted type of 
its operands. 
If this promoted type is int or long, then integer arithmetic is performed. 


If this promoted type is float or double, then floating-point arithmetic is 
performed. 


Addition is a commutative operation if the operand expressions have no side 
effects. 


Integer addition is associative when the operands are all of the same type. 
Floating-point addition is not associative. 


If an integer addition overflows, then the result is the low-order bits of the 
mathematical sum as represented in some sufficiently large two's-complement 
format. If overflow occurs, then the sign of the result is not the same as the sign of 
the mathematical sum of the two operand values. 


The result of a floating-point addition is determined using the following rules of 
IEEE 754 arithmetic: 


¢ If either operand is NaN, the result is NaN. 

¢ The sum of two infinities of opposite sign is NaN. 

¢ The sum of two infinities of the same sign is the infinity of that sign. 

¢ The sum of an infinity and a finite value is equal to the infinite operand. 
¢ The sum of two zeros of opposite sign is positive zero. 

¢ The sum of two zeros of the same sign is the zero of that sign. 


e The sum of a zero and a nonzero finite value is equal to the nonzero operand. 
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¢ The sum of two nonzero finite values of the same magnitude and opposite sign 
1S positive zero. 


¢ Inthe remaining cases, where neither an infinity, nor a zero, nor NaN is involved, 
and the operands have the same sign or have different magnitudes, the exact 
mathematical sum is computed. A floating-point value set is then chosen: 


— If the addition expression is FP-strict ($15.4): 


>» If the type of the addition expression is float, then the float value set must 
be chosen. 


>» If the type of the addition expression is double, then the double value set 
must be chosen. 


— If the addition expression is not FP-strict: 


>» If the type of the addition expression is float, then either the float value 
set or the float-extended-exponent value set may be chosen, at the whim of 
the implementation. 


>» Ifthe type of the addition expression is double, then either the double value 
set or the double-extended-exponent value set may be chosen, at the whim 
of the implementation. 


Next, a value must be chosen from the chosen value set to represent the sum. 


If the magnitude of the sum is too large to represent, we say the operation 
overflows; the result is then an infinity of appropriate sign. 


Otherwise, the sum is rounded to the nearest value in the chosen value set using 
IEEE 754 round-to-nearest mode. The Java programming language requires 
support of gradual underflow as defined by IEEE 754 (84.2.4). 


The binary - operator performs subtraction when applied to two operands of 
numeric type, producing the difference of its operands; the left-hand operand is the 
minuend and the right-hand operand is the subtrahend. 


For both integer and floating-point subtraction, it is always the case that a-b 
produces the same result as a+ (-b). 


Note that, for integer values, subtraction from zero is the same as negation. 
However, for floating-point operands, subtraction from zero is not the same as 
negation, because if x is +0.0, then 0.0-x is +0.0, but -x is -0.0. 


Despite the fact that overflow, underflow, or loss of information may occur, 
evaluation of a numeric additive operator never throws a run-time exception. 
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15.19 Shift Operators 


The operators << (left shift), >> (signed right shift), and >>> (unsigned right shift) 
are called the shift operators. The left-hand operand of a shift operator is the value 
to be shifted; the right-hand operand specifies the shift distance. 


ShiftExpression: 
AdditiveExpression 
ShiftExpression << AdditiveExpression 
ShiftExpression >> AdditiveExpression 
ShiftExpression >>> AdditiveExpression 


The shift operators are syntactically left-associative (they group left-to-right). 


Unary numeric promotion (§5.6.1) is performed on each operand separately. 
(Binary numeric promotion (§5.6.2) is not performed on the operands.) 


It is a compile-time error if the type of each of the operands of a shift operator, 
after unary numeric promotion, is not a primitive integral type. 


The type of the shift expression is the promoted type of the left-hand operand. 


If the promoted type of the left-hand operand is int, then only the five lowest-order 
bits of the right-hand operand are used as the shift distance. It is as if the right-hand 
operand were subjected to a bitwise logical AND operator « (§15.22.1) with the 
mask value 0x1£ (0b11111). The shift distance actually used is therefore always in 
the range 0 to 31, inclusive. 


If the promoted type of the left-hand operand is long, then only the six lowest- 
order bits of the right-hand operand are used as the shift distance. It is as if the 
right-hand operand were subjected to a bitwise logical AND operator « (§15.22.1) 
with the mask value 0x3f (0b111111). The shift distance actually used is therefore 
always in the range 0 to 63, inclusive. 


At run time, shift operations are performed on the two's-complement integer 
representation of the value of the left operand. 


The value of 1 << s is n left-shifted s bit positions; this is equivalent (even if 
overflow occurs) to multiplication by two to the power s. 


The value of n >> s is n right-shifted s bit positions with sign-extension. The 
resulting value is floor(n / 2°). For non-negative values of n, this is equivalent to 
truncating integer division, as computed by the integer division operator /, by two 
to the power s. 
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The value of n >>> 5 is n right-shifted s bit positions with zero-extension, where: 
¢ If 7 is positive, then the result is the same as that of n >> s. 


¢ If n is negative and the type of the left-hand operand is int, then the result is 
equal to that of the expression (n >> 5) + (2 << ~s). 


¢ If n is negative and the type of the left-hand operand is long, then the result is 
equal to that of the expression (n >> 5) + (2L << ~S). 


The added term (2 << ~s) or (2L << ~s) cancels out the propagated sign bit. 


Note that, because of the implicit masking of the right-hand operand of a shift operator, 
~s as a shift distance is equivalent to 31-s when shifting an int value and to 63-s when 
shifting a Long value. 


15.20 Relational Operators 


The numerical comparison operators <, >, <=, and >=, and the instanceof operator, 
are called the relational operators. 


RelationalExpression: 
ShiftExpression 
RelationalExpression < ShiftExpression 
RelationalExpression > ShiftExpression 
RelationalExpression <= ShiftExpression 
RelationalExpression >= ShiftExpression 
RelationalExpression instanceof ReferenceType 


The relational operators are syntactically left-associative (they group left-to-right). 


However, this fact is not useful. For example, a<b<c parses as (a<b) <c, which is always 
a compile-time error, because the type of a<b is always boolean and < is not an operator 
on boolean values. 


The type of a relational expression is always boolean. 


15.20.1_ Numerical Comparison Operators <, <=, >, and >= 


The type of each of the operands of a numerical comparison operator must be a 
type that is convertible (§5.1.8) to a primitive numeric type, or a compile-time error 
occurs. 
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Binary numeric promotion is performed on the operands (§5.6.2). 


Note that binary numeric promotion performs value set conversion (§5.1.13) and may 
perform unboxing conversion (§5.1.8). 


If the promoted type of the operands is int or long, then signed integer comparison 
is performed. 


If the promoted type is float or double, then floating-point comparison is 
performed. 


Comparison is carried out accurately on floating-point values, no matter what value 
sets their representing values were drawn from. 


The result of a floating-point comparison, as determined by the specification of the 
IEEE 754 standard, is: 


¢ If either operand is NaN, then the result is false. 


¢ All values other than NaN are ordered, with negative infinity less than all finite 
values, and positive infinity greater than all finite values. 


¢ Positive zero and negative zero are considered equal. 
For example, -0.0<0.0 is false, but -0.0<=0.0 is true. 


Note, however, that the methods Math.min and Math.max treat negative zero as being 
strictly smaller than positive zero. 


Subject to these considerations for floating-point numbers, the following rules then 
hold for integer operands or for floating-point operands other than NaN: 


¢ The value produced by the < operator is t rue if the value of the left-hand operand 
is less than the value of the right-hand operand, and otherwise is false. 


¢ The value produced by the <= operator is true if the value of the left-hand 
operand is less than or equal to the value of the right-hand operand, and otherwise 
iS false. 


¢ The value produced by the > operator is t rue if the value of the left-hand operand 
is greater than the value of the right-hand operand, and otherwise is false. 


e The value produced by the >= operator is true if the value of the left-hand 
operand is greater than or equal to the value of the right-hand operand, and 
otherwise is false. 
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15.20.2 Type Comparison Operator instanceof 


The type of the RelationalExpression operand of the instanceof operator must be 
a reference type or the null type, or a compile-time error occurs. 


It is a compile-time error if the ReferenceType mentioned after the instanceof 
operator does not denote a reference type that is reifiable ($4.7). 


If a cast of the RelationalExpression to the ReferenceType would be rejected as a 
compile-time error (§15.16), then the instanceof relational expression likewise 
produces a compile-time error. In such a situation, the result of the instanceof 
expression could never be true. 


At run time, the result of the instanceof operator is true if the value of 
the RelationalExpression is not null and the reference could be cast to the 
ReferenceType without raising a ClassCastException. Otherwise the result is 


false. 


Example 15.20.2-1. The instanceof Operator 


class Point { int x, y; } 
class Element { int atomicNumber; } 
class Test { 
public static void main(String[] args) { 
Point p = new Point (); 
Element e = new Element (); 
if (e instanceof Point) { // compile-time error 
System.out.printin("I get your point!"); 
p = (Point)e; // compile-time error 


This program results in two compile-time errors. The cast (Point) eis incorrect because no 
instance of Element or any of its possible subclasses (none are shown here) could possibly 
be an instance of any subclass of Point. The instanceof expression is incorrect for 
exactly the same reason. If, on the other hand, the class Point were a subclass of Element 
(an admittedly strange notion in this example): 


class Point extends Element { int x, y; } 


then the cast would be possible, though it would require a run-time check, and the 
instanceof expression would then be sensible and valid. The cast (Point) e would never 
raise an exception because it would not be executed if the value of e could not correctly 
be cast to type Point. 
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15.21 Equality Operators 


The operators == (equal to) and != (not equal to) are called the equality operators. 


EqualityExpression: 
RelationalExpression 
EqualityExpression == RelationalExpression 
EqualityExpression != RelationalExpression 


The equality operators are syntactically left-associative (they group left-to-right). 


However, this fact is essentially never useful. For example, a==b==c parses as (a==b) ==c. 
The result type of a==b is always boolean, and c must therefore be of type boolean or 
a compile-time error occurs. Thus, a==b==c does not test to see whether a, b, and c are 
all equal. 


The equality operators are commutative if the operand expressions have no side 
effects. 


The equality operators are analogous to the relational operators except for their 
lower precedence. Thus, a<b==c<d i$ true whenever a<b and c<d have the same 
truth value. 


The equality operators may be used to compare two operands that are convertible 
($5.1.8) to numeric type, or two operands of type boolean or Boolean, or two 
operands that are each of either reference type or the null type. All other cases result 
in a compile-time error. 


The type of an equality expression is always boolean. 


In all cases, a!=b produces the same result as ! (a==b). 


15.21.1 Numerical Equality Operators == and != 


If the operands of an equality operator are both of numeric type, or one is of 
numeric type and the other is convertible ($5.1.8) to numeric type, binary numeric 
promotion is performed on the operands (§5.6.2). 


Note that binary numeric promotion performs value set conversion (§5.1.13) and may 
perform unboxing conversion (§5.1.8). 


If the promoted type of the operands is int or long, then an integer equality test 
is performed. 
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If the promoted type is float or double, then a floating-point equality test is 
performed. 


Comparison is carried out accurately on floating-point values, no matter what value 
sets their representing values were drawn from. 


Floating-point equality testing is performed in accordance with the rules of the 
IEEE 754 standard: 


¢ If either operand is NaN, then the result of == is false but the result of !=is true. 


Indeed, the test x!=x is true if and only if the value of x is NaN. 


The methods Float .isNaN and Double.isNaN may also be used to test whether a 
value is NaN. 


¢ Positive zero and negative zero are considered equal. 


For example, -0.0==0.0 is true. 


¢ Otherwise, two distinct floating-point values are considered unequal by the 
equality operators. 


In particular, there is one value representing positive infinity and one value 
representing negative infinity; each compares equal only to itself, and each 
compares unequal to all other values. 


Subject to these considerations for floating-point numbers, the following rules then 
hold for integer operands or for floating-point operands other than NaN: 


¢ The value produced by the == operator is true if the value of the left-hand 
operand is equal to the value of the right-hand operand; otherwise, the result is 


false. 


¢ The value produced by the != operator is true if the value of the left-hand 
operand is not equal to the value of the right-hand operand; otherwise, the result 
iS false. 


15.21.2 Boolean Equality Operators == and != 


If the operands of an equality operator are both of type boolean, or if one operand 
is of type boolean and the other is of type Boolean, then the operation is boolean 
equality. 


The boolean equality operators are associative. 


If one of the operands is of type Boolean, it is subjected to unboxing conversion 
($5.1.8). 
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The result of == is true if the operands (after any required unboxing conversion) 
are both true or both false; otherwise, the result is false. 


The result of != is false if the operands are both true or both false; otherwise, 
the result is true. 


Thus != behaves the same as * ($15.22.2) when applied to boolean operands. 


15.21.3 Reference Equality Operators == and != 


If the operands of an equality operator are both of either reference type or the null 
type, then the operation is object equality. 


It is a compile-time error if it is impossible to convert the type of either operand 
to the type of the other by a casting conversion (§5.5). The run-time values of the 
two operands would necessarily be unequal (ignoring the case where both values 
are null). 


At run time, the result of == is true if the operand values are both null or both 
refer to the same object or array; otherwise, the result is false. 


The result of != is false if the operand values are both nu11 or both refer to the 
same object or array; otherwise, the result is true. 


While == may be used to compare references of type string, such an equality test 
determines whether or not the two operands refer to the same string object. The 
result is false if the operands are distinct st ring objects, even if they contain the 
same sequence of characters (§3.10.5). The contents of two strings s and t can be 
tested for equality by the method invocation s.equals (t). 


15.22 Bitwise and Logical Operators 


The bitwise operators and logical operators include the AND operator «, exclusive 
OR operator *, and inclusive OR operator |. 


AndExpression: 
EqualityExpression 
AndExpression s EqualityExpression 


ExclusiveOrExpression: 
AndExpression 
ExclusiveOrExpression * AndExpression 
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InclusiveOrExpression: 
ExclusiveOrExpression 
InclusiveOrExpression | ExclusiveOrExpression 


These operators have different precedence, with « having the highest precedence 
and | the lowest precedence. 


Each of these operators is syntactically left-associative (each groups left-to-right). 
Each operator is commutative if the operand expressions have no side effects. 
Each operator is associative. 


The bitwise and logical operators may be used to compare two operands of numeric 
type or two operands of type boolean. All other cases result in a compile-time error. 


15.22.1 Integer Bitwise Operators «, *, and | 


When both operands of an operator «, *, or | are of a type that is convertible (§5.1.8) 
to a primitive integral type, binary numeric promotion is first performed on the 
operands (§5.6.2). 


The type of the bitwise operator expression is the promoted type of the operands. 
For «, the result value is the bitwise AND of the operand values. 
For *, the result value is the bitwise exclusive OR of the operand values. 
For |, the result value is the bitwise inclusive OR of the operand values. 

For example, the result of the expression: 

Oxff£00 & Oxf0£0 

is: 

0x£000 

The result of the expression: 

Oxf£00 * Ox£0£0 

is: 

Ox0f£0 


The result of the expression: 
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Oxff00 | Oxf0£0 
is: 


Oxfff0 


15.22.2 Boolean Logical Operators «, *, and | 


When both operands of a «, *, or | operator are of type boolean or Boolean, then 
the type of the bitwise operator expression is boolean. In all cases, the operands 
are subject to unboxing conversion (§5.1.8) as necessary. 


For «, the result value is t rue if both operand values are t rue; otherwise, the result 
iS false. 


For *, the result value is true if the operand values are different; otherwise, the 
result is false. 


For |, the result value is false if both operand values are false; otherwise, the 
result is true. 


15.23 Conditional-And Operator «<< 


The conditional-and operator «« is like « (§15.22.2), but evaluates its right-hand 
operand only if the value of its left-hand operand is true. 


ConditionalAndExpression: 
InclusiveOrExpression 
ConditionalAndExpression && InclusiveOrExpression 


The conditional-and operator is syntactically left-associative (it groups left-to- 
right). 


The conditional-and operator is fully associative with respect to both side effects 
and result value. That is, for any expressions a, b, and c, evaluation of the 
expression ((a) && (b)) && (c) produces the same result, with the same side 
effects occurring in the same order, as evaluation of the expression (a) && ((b) 
&& (C)). 


Each operand of the conditional-and operator must be of type boolean Or Boolean, 
or a compile-time error occurs. 


The type of a conditional-and expression is always boolean. 


15.23 


601 


15.24 


602 


Conditional-Or Operator | | EXPRESSIONS 


At run time, the left-hand operand expression is evaluated first; if the result has 
type Boolean, it is subjected to unboxing conversion (§5.1.8). 


If the resulting value is false, the value of the conditional-and expression is false 
and the right-hand operand expression is not evaluated. 


If the value of the left-hand operand is true, then the right-hand expression is 
evaluated; if the result has type Boolean, it is subjected to unboxing conversion 
($5.1.8). The resulting value becomes the value of the conditional-and expression. 


Thus, && computes the same result as & on boolean operands. It differs only in that 
the right-hand operand expression is evaluated conditionally rather than always. 


15.24 Conditional-Or Operator | | 


The conditional-or operator | | operator is like | ($15.22.2), but evaluates its right- 
hand operand only if the value of its left-hand operand is false. 


ConditionalOrExpression: 
ConditionalAndExpression 
ConditionalOrExpression | | ConditionalAndExpression 


The conditional-or operator is syntactically left-associative (it groups left-to-right). 


The conditional-or operator is fully associative with respect to both side effects and 
result value. That is, for any expressions a, b, and c, evaluation of the expression 
((a) || (b)) || (e) produces the same result, with the same side effects 
occurring in the same order, as evaluation of the expression (a) || ((b) || (c¢)). 


Each operand of the conditional-or operator must be of type boolean Or Boolean, 
or a compile-time error occurs. 


The type of a conditional-or expression is always boolean. 


At run time, the left-hand operand expression is evaluated first; if the result has 
type Boolean, it is subjected to unboxing conversion (§5.1.8). 


If the resulting value is true, the value of the conditional-or expression is true and 
the right-hand operand expression is not evaluated. 


If the value of the left-hand operand is false, then the right-hand expression is 
evaluated; if the result has type Boolean, it is subjected to unboxing conversion 
($5.1.8). The resulting value becomes the value of the conditional-or expression. 
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Thus, | | computes the same result as | on boolean or Boolean operands. It differs 
only in that the right-hand operand expression is evaluated conditionally rather than 
always. 


15.25 Conditional Operator ? 


The conditional operator 2: uses the boolean value of one expression to decide 
which of two other expressions should be evaluated. 


ConditionalExpression: 
ConditionalOrExpression 
ConditionalOrExpression ? Expression : ConditionalExpression 
ConditionalOrExpression ? Expression : LambdaExpression 


The conditional operator is syntactically right-associative (it groups right-to-left). 
Thus, a?b:c?d:e?f:g means the same as a?b: (c?d: (e?f:g)). 


The conditional operator has three operand expressions. ? appears between the first 
and second expressions, and : appears between the second and third expressions. 


The first expression must be of type boolean Or Boolean, or a compile-time error 
occurs. 


It is a compile-time error for either the second or the third operand expression to 
be an invocation of a void method. 


In fact, by the grammar of expression statements (§ 14.8), it is not permitted for a conditional 
expression to appear in any context where an invocation of a void method could appear. 


There are three kinds of conditional expressions, classified according to the 
second and third operand expressions: boolean conditional expressions, numeric 
conditional expressions, and reference conditional expressions. The classification 
rules are as follows: 


¢ If both the second and the third operand expressions are boolean expressions, 
the conditional expression is a boolean conditional expression. 


For the purpose of classifying a conditional, the following expressions are 
boolean expressions: 


— Anexpression of a standalone form (§15.2) that has type boolean or Boolean. 


— A parenthesized boolean expression (§15.8.5). 
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— Aclass instance creation expression ($15.9) for class Boolean. 


— A method invocation expression ($15.12) for which the chosen most specific 
method (§15.12.2.5) has return type boolean Or Boolean. 


Note that, for a generic method, this is the type before instantiating the method's type 
arguments. 


— A boolean conditional expression. 


¢ If both the second and the third operand expressions are numeric expressions, 
the conditional expression is a numeric conditional expression. 


For the purpose of classifying a conditional, the following expressions are 
numeric expressions: 


— An expression of a standalone form ($15.2) with a type that is convertible to 
a numeric type (§4.2, §5.1.8). 


— A parenthesized numeric expression (§15.8.5). 


— A class instance creation expression (§15.9) for a class that is convertible to 
a numeric type. 


— A method invocation expression ($15.12) for which the chosen most specific 
method (§$15.12.2.5) has a return type that is convertible to a numeric type. 


Note that, for a generic method, this is the type before instantiating the method's type 
arguments. 


— A numeric conditional expression. 
¢ Otherwise, the conditional expression is a reference conditional expression. 


The process for determining the type of a conditional expression depends on the 
kind of conditional expression, as outlined in the following sections. 


The following tables summarize the rules above by giving the type of a conditional 
expression for all possible types of its second and third operands. bnp(..) means to 
apply binary numeric promotion. The form "r| bnp(..)" is used where one operand 
is a constant expression of type int and may be representable in type 1, where 
binary numeric promotion is used if the operand is not representable in type r. The 
operand type Object means any reference type other than the nu11 type and the 
eight wrapper classes Boolean, Byte, Short, Character, Integer, Long, Float, 
Double. 
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Table 15.25-A. Conditional expression type (Primitive 3rd operand, Part I) 


3rd > byte short char int 
2nd J 
byte byte short bnp(byte,char) byte | bnp(byte,int) 
Byte byte short bnp(Byte,char) byte | bnp(Byte,int) 
short short short bnp(short,char) short | bnp(short,int) 
Short short short bnp(Short,char) short | bnp(Short,int) 
char bnp(char,byte) bnp(char,short) char char | bnp(char,int) 
Character bnp(Character,byte) bnp(Character,short) char char | bnp(Character,int) 
int byte | bnp(int,byte) short | bnp(int,short) char | bnp(int,char) int 
Integer bnp(Integer,byte) bnp(Integer,short) bnp(Integer,char) int 
long bnp(long,byte) bnp(long,short) bnp(long,char) bnp(long,int) 
Long bnp(Long,byte) bnp(Long,short) bnp(Long,char) bnp(Long,int) 
float bnp(f£loat,byte) bnp(float,short) bnp(£loat,char) bnp(£loat,int) 
Float bnp(Float,byte) bnp(Float,short) bnp(Float,char) bnp(Float,int) 
double bnp(double,byte) bnp(double,short) bnp(double,char) bnp(double,int) 
Double bnp(Double,byte) bnp(Double,short) bnp(Double,char) bnp(Double,int) 
boolean lub(Boolean,Byte) lub(Boolean,Short) lub(Boolean,Character) lub(Boolean, Integer) 
Boolean lub(Boolean,Byte) lub(Boolean,Short) lub(Boolean,Character) lub(Boolean,Integer) 
null lub(nu11,Byte) lub(null,Short) lub(null,Character) lub(null,Integer) 
Object lub(Object,Byte) lub(Object,Short) lub(Object,Character) lub(Object,Integer) 
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Table 15.25-B. Conditional expression type (Primitive 3rd operand, Part II) 


3rd > 


2nd J 


long 


float 


double 


boolean 


byte 


Byte 


bnp(byte,long) 


bnp(Byte,long) 


bnp(byte,float) 


bnp(Byte,float) 


bnp(byte,double) 


bnp(Byte,double) 


lub(Byte,Boolean) 


lub(Byte,Boolean) 


short 


Short 


bnp(short,long) 


bnp(Short,long) 


bnp(short,float) 


bnp(Short,float) 


bnp(short,double) 


bnp(Short,double) 


lub(Short,Boolean) 


lub(Short,Boolean) 


char 


Character 


bnp(char,long) 


bnp(Character,long) 


bnp(char,float) 


bnp(Character,float) 


bnp(char,double) 


bnp(Character,double) 


lub(Character,Boolean) 


lub(Character,Boolean) 


int 


Integer 


bnp(int,long) 


bnp(Integer,long) 


bnp(int,float) 


bnp(Integer,float) 


bnp(int,double) 


bnp(Integer,double) 


lub(Integer,Boolean) 


lub(Integer,Boolean) 


long 


Long 


long 


long 


bnp(long,float) 


bnp(Long,float) 


bnp(long,double) 


bnp(Long,double) 


lub(Long,Boolean) 


lub(Long,Boolean) 


float 


Float 


bnp(£loat,long) 


bnp(Float,long) 


float 


float 


bnp(f£loat,double) 


bnp(F loat,double) 


lub(F loat,Boolean) 


lub(F loat,Boolean) 


double 


Double 


bnp(double,long) 


bnp(Double,long) 


bnp(double,float) 


bnp(Double,float) 


double 


double 


lub(Double,Boolean) 


lub(Double,Boolean) 


boolean 


Boolean 


lub(Boolean,Long) 


lub(Boolean,Long) 


lub(Boolean,Float) 


lub(Boolean,Float) 


lub(Boolean,Double) 


lub(Boolean,Double) 


boolean 


boolean 


null 


Object 


lub(null,Long) 


lub(Ob ject,Long) 


lub(null,Float) 


lub(Ob ject,Float) 


lub(null,Double) 


lub(Ob ject Double) 


lub(nul1,Boolean) 


lub(Object,Boolean) 
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Table 15.25-C. Conditional expression type (Reference 3rd operand, Part I) 


3rd > Byte Short Character Integer 

2nd J 

byte byte short bnp(byte,Character) bnp(byte,Integer) 
Byte Byte short bnp(Byte,Character) bnp(Byte,Integer) 
short short short bnp(short,Character) bnp(short,Integer) 
Short short Short bnp(Short,Character) bnp(Short,Integer) 
char bnp(char,Byte) bnp(char,Short) char bnp(char,Integer) 
Character bnp(Character,Byte) bnp(Character,Short) Character bnp(Character,Integer) 
int byte|bnp(int,Byte) short |bnp(int,short) char | bnp(int,character) int 
Integer bnp(Integer,Byte) bnp(Integer,Short) bnp(Integer,Character) Integer 

long bnp(long,Byte) bnp(long,Short) bnp(long,Character) bnp(long,Integer) 
Long bnp(Long,Byte) bnp(Long,Short) bnp(Long,Character) bnp(Long,Integer) 
float bnp(f£loat,Byte) bnp(£loat,Short) bnp(float,Character) bnp(£loat,Integer) 
Float bnp(F loat,Byte) bnp(Float,Short) bnp(F loat,Character) bnp(Float,Integer) 
double bnp(double,Byte) bnp(double,Short) bnp(double,Character) bnp(double,Integer) 
Double bnp(Double,Byte) bnp(Double,Short) bnp(Double,Character) bnp(Double,Integer) 
boolean lub(Boolean,Byte) lub(Boolean,Short) lub(Boolean,Character) lub(Boolean,Integer) 
Boolean lub(Boolean,Byte) lub(Boolean,Short) lub(Boolean,Character) lub(Boolean, Integer) 
null Byte Short Character Integer 
Object lub(Ob ject,Byte) lub(Object,Short) lub(Object,Character) lub(Object,Integer) 
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Table 15.25-D. Conditional expression type (Reference 3rd operand, Part ID) 


3rd > Long Float Double Boolean 

2nd L 

byte bnp(byte,Long) bnp(byte,Float) bnp(byte,Double) lub(Byte,Boolean) 
Byte bnp(Byte,Long) bnp(Byte,Float) bnp(Byte,Double) lub(Byte,Boolean) 
short bnp(short,Long) bnp(short,Float) bnp(short,Double) lub(Short,Boolean) 
Short bnp(Short,Long) bnp(Short,Float) bnp(Short,Double) lub(Short,Boolean) 
char bnp(char,Long) bnp(char,Float) bnp(char,Double) lub(Character,Boolean) 
Character bnp(Character,Long) bnp(Character,Float) bnp(Character,Double) lub(Character,Boolean) 
int bnp(int,Long) bnp(int,Float) bnp(int,Double) lub(Integer,Boolean) 
Integer bnp(Integer,Long) bnp(Integer,Float) bnp(Integer,Double) lub(Integer,Boolean) 
long long bnp(long,Float) bnp(long,Double) lub(Long,Boolean) 
Long Long bnp(Long,Float) bnp(Long,Double) lub(Long,Boolean) 
float bnp(£loat,Long) float bnp(f£loat,Double) lub(F loat,Boolean) 
Float bnp(F Loat,Long) Float bnp(F loat,Double) lub(F loat,Boolean) 
double bnp(double,Long) bnp(double,Float) double lub(Double,Boolean) 
Double bnp(Double,Long) bnp(Double,Float) Double lub(Double,Boolean) 
boolean lub(Boolean,Long) lub(Boolean,Float) lub(Boolean,Double) boolean 
Boolean lub(Boolean,Long) lub(Boolean,Float) lub(Boolean,Double) Boolean 

null Long Float Double Boolean 
Object lub(Ob ject,Long) lub(Ob ject,Float) lub(Ob ject Double) lub(Ob ject,Boolean) 
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Table 15.25-E. Conditional expression type (Reference 3rd operand, Part III) 


Conditional Operator ? 


3rd > null Object 

2nd J 

byte lub(Byte,null) lub(Byte,Ob ject) 
Byte Byte lub(Byte,Object) 
short lub(Short,null) lub(Short,Ob ject) 
Short Short lub(Short,Object) 
char lub(Character,null) lub(Character,Object) 
Character Character lub(Character,Object) 
int lub(Integer,null) lub(Integer,Object) 
Integer Integer lub(Integer,Object) 
long lub(Long,nu11) lub(Long,Object) 
Long Long lub(Long,Ob ject) 
float lub(Float,null) lub(Float,Ob ject) 
Float Float lub(Float,Object) 
double lub(Double,null) lub(Double,Object) 
Double Double lub(Double,Object) 
boolean lub(Boolean,null) lub(Boolean,Object) 
Boolean Boolean lub(Boolean,Object) 
null null lub(nul1,Object) 
Object Object Object 


At run time, the first operand expression of the conditional expression is evaluated 


first. If necessary, unboxing conversion is performed on the result. 


The resulting boolean value is then used to choose either the second or the third 


operand expression: 


¢ If the value of the first operand is true, then the second operand expression is 


chosen. 


¢ If the value of the first operand is false, then the third operand expression is 


chosen. 
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The chosen operand expression is then evaluated and the resulting value is 
converted to the type of the conditional expression as determined by the rules stated 
below. 


This conversion may include boxing or unboxing conversion (§5.1.7, §5.1.8). 


The operand expression not chosen is not evaluated for that particular evaluation 
of the conditional expression. 


15.25.1 Boolean Conditional Expressions 


Boolean conditional expressions are standalone expressions (§15.2). 
The type of a boolean conditional expression is determined as follows: 


e If the second and third operands are both of type Boolean, the conditional 
expression has type Boolean. 


¢ Otherwise, the conditional expression has type boolean. 


15.25.2 Numeric Conditional Expressions 


Numeric conditional expressions are standalone expressions (§15.2). 
The type of a numeric conditional expression is determined as follows: 


¢ If the second and third operands have the same type, then that is the type of the 
conditional expression. 


¢ If one of the second and third operands is of primitive type r, and the type of the 
other is the result of applying boxing conversion (§5.1.7) to 7, then the type of 
the conditional expression is T. 


¢ If one of the operands is of type byte or Byte and the other is of type short or 
Short, then the type of the conditional expression is short. 


¢ If one of the operands is of type rT where T is byte, short, or char, and the 
other operand is a constant expression ($15.28) of type int whose value is 
representable in type r, then the type of the conditional expression is T. 


¢ If one of the operands is of type T, where Tis Byte, Short, Of Character, and the 
other operand is a constant expression of type int whose value is representable 
in the type u which is the result of applying unboxing conversion to r, then the 
type of the conditional expression is vu. 
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¢ Otherwise, binary numeric promotion (§5.6.2) is applied to the operand types, 
and the type of the conditional expression is the promoted type of the second 
and third operands. 


Note that binary numeric promotion performs value set conversion (§5.1.13) and may 
perform unboxing conversion (§5.1.8). 


15.25.3 Reference Conditional Expressions 


A reference conditional expression is a poly expression if it appears in an 
assignment context or an invocation context (§5.2. §5.3). Otherwise, it is a 
standalone expression. 


Where a poly reference conditional expression appears in a context of a particular 
kind with target type 1, its second and third operand expressions similarly appear 
in acontext of the same kind with target type r. 


A poly reference conditional expression is compatible with a target type r if its 
second and third operand expressions are compatible with r. 


The type of a poly reference conditional expression is the same as its target type. 
The type of a standalone reference conditional expression is determined as follows: 


¢ Ifthe second and third operands have the same type (which may be the null type), 
then that is the type of the conditional expression. 


¢ If the type of one of the second and third operands is the null type, and the type of 
the other operand is a reference type, then the type of the conditional expression 
is that reference type. 


¢ Otherwise, the second and third operands are of types s; and sz respectively. 
Let rT, be the type that results from applying boxing conversion to s;, and let r, 
be the type that results from applying boxing conversion to s2. The type of the 
conditional expression is the result of applying capture conversion (§5.1.10) to 
lub(T;, T>). 


Because reference conditional expressions can be poly expressions, they can "pass 
down" context to their operands. This allows lambda expressions and method reference 
expressions to appear as operands: 


return ... ? (x -> x) : (x -> -x); 


It also allows use of extra information to improve type checking of generic method 
invocations. Prior to Java SE 8, this assignment was well-typed: 


List<String> ls = Arrays.asList(); 
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but this was not: 
List<String> ls = ... ? Arrays.asList() : Arrays.asList("a","b"); 
The rules above allow both assignments to be considered well-typed. 


Note that a reference conditional expression does not have to contain a poly expression as 
an operand in order to be a poly expression. It is a poly expression simply by virtue of the 
context in which it appears. For example, in the following code, the conditional expression 
is a poly expression, and each operand is considered to be in an assignment context targeting 
Class<? super Integer>: 


Class<? super Integer> choose(boolean b, 
Class<Integer> cl, 
Class<Number> c2) { 
return b ? cl : c2; 


If the conditional expression was not a poly expression, then a compile-time error would 
occur, as its type would be lub(Class<Integer>, Class<Number>)=Class<? extends 
Number> which is incompatible with the return type of choose. 


15.26 Assignment Operators 


There are 12 assignment operators; all are syntactically right-associative (they 
group right-to-left). Thus, a=b=c means a= (b=c), which assigns the value of c to 
b and then assigns the value of b to a. 


AssignmentExpression: 
ConditionalExpression 
Assignment 


Assignment: 
LeftHandSide AssignmentOperator Expression 


LeftHandSide: 
ExpressionName 
FieldAccess 
ArrayAccess 


AssignmentOperator: 


(one of) 


/ 


<< >> PP & x 


oe 
+ 
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The result of the first operand of an assignment operator must be a variable, or a 
compile-time error occurs. 


This operand may be a named variable, such as a local variable or a field of the 
current object or class, or it may be a computed variable, as can result from a field 
access (§15.11) or an array access (§15.10.3). 


The type of the assignment expression is the type of the variable after capture 
conversion (§5.1.10). 


At run time, the result of the assignment expression is the value of the variable 
after the assignment has occurred. The result of an assignment expression is not 
itself a variable. 


A variable that is declared final cannot be assigned to (unless it is definitely 
unassigned (§16 (Definite Assignment))), because when an access of such a final 
variable is used as an expression, the result is a value, not a variable, and so it 
cannot be used as the first operand of an assignment operator. 


15.26.1 Simple Assignment Operator = 


If the type of the right-hand operand is not assignment compatible with the type of 
the variable (§5.2), then a compile-time error occurs. 


Otherwise, at run time, the expression is evaluated in one of three ways. 


If the left-hand operand expression is a field access expression e. f ($15.11), 
possibly enclosed in one or more pairs of parentheses, then: 


e First, the expression e is evaluated. If evaluation of e completes abruptly, the 
assignment expression completes abruptly for the same reason. 


¢ Next, the right hand operand is evaluated. If evaluation of the right hand 
expression completes abruptly, the assignment expression completes abruptly 
for the same reason. 


¢ Then, if the field denoted by e. fis not static and the result of the evaluation 
of e above is null, then a Nul1PointerException is thrown. 


¢ Otherwise, the variable denoted by e. f is assigned the value of the right hand 
operand as computed above. 


If the left-hand operand is an array access expression ($15.10.3), possibly enclosed 
in One or more pairs of parentheses, then: 


¢ First, the array reference subexpression of the left-hand operand array access 
expression is evaluated. If this evaluation completes abruptly, then the 
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assignment expression completes abruptly for the same reason; the index 
subexpression (of the left-hand operand array access expression) and the right- 
hand operand are not evaluated and no assignment occurs. 


Otherwise, the index subexpression of the left-hand operand array access 
expression is evaluated. If this evaluation completes abruptly, then the 
assignment expression completes abruptly for the same reason and the right-hand 
operand is not evaluated and no assignment occurs. 


Otherwise, the right-hand operand is evaluated. If this evaluation completes 
abruptly, then the assignment expression completes abruptly for the same reason 
and no assignment occurs. 


Otherwise, if the value of the array reference subexpression is null, then no 
assignment occurs and a Nul1lPointerException is thrown. 


Otherwise, the value of the array reference subexpression indeed refers to an 
array. If the value of the index subexpression is less than zero, or greater 
than or equal to the length of the array, then no assignment occurs and an 
ArrayIndexOutOfBoundsException Is thrown. 


Otherwise, the value of the index subexpression is used to select a component of 
the array referred to by the value of the array reference subexpression. 


This component is a variable; call its type sc. Also, let rc be the type of the left- 
hand operand of the assignment operator as determined at compile time. Then 
there are two possibilities: 


— If rcis a primitive type, then sc is necessarily the same as Tc. 


The value of the right-hand operand is converted to the type of the selected 
array component, is subjected to value set conversion (§5.1.13) to the 
appropriate standard value set (not an extended-exponent value set), and the 
result of the conversion is stored into the array component. 


— If rcis a reference type, then sc may not be the same as rc, but rather a type 
that extends or implements rc. 


Let Rc be the class of the object referred to by the value of the right-hand 
operand at run time. 


A Java compiler may be able to prove at compile time that the array component 
will be of type rc exactly (for example, rc might be final). But if a Java 
compiler cannot prove at compile time that the array component will be of 
type Tc exactly, then a check must be performed at run time to ensure that the 
class Rc is assignment compatible (§5.2) with the actual type sc of the array 
component. 
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This check is similar to a narrowing cast (§5.5, §15.16), except that if the check fails, 
an ArrayStoreException is thrown rather than a ClassCastException 


If class Rc is not assignable to type sc, then no assignment occurs and an 
ArrayStoreException is thrown. 


Otherwise, the reference value of the right-hand operand is stored into the 
selected array component. 


Otherwise, three steps are required: 


¢ First, the left-hand operand is evaluated to produce a variable. If this evaluation 
completes abruptly, then the assignment expression completes abruptly for the 
same reason; the right-hand operand is not evaluated and no assignment occurs. 


¢ Otherwise, the right-hand operand is evaluated. If this evaluation completes 
abruptly, then the assignment expression completes abruptly for the same reason 
and no assignment occurs. 


¢ Otherwise, the value of the right-hand operand is converted to the type of the left- 
hand variable, is subjected to value set conversion (§5.1.13) to the appropriate 
standard value set (not an extended-exponent value set), and the result of the 
conversion is stored into the variable. 


Example 15.26.1-1. Simple Assignment To An Array Component 


class ArrayReferenceThrow extends RuntimeException { } 
class IndexThrow extends RuntimeException { } 
class RightHandSideThrow extends RuntimeException { } 


class IllustrateSimpleArrayAssignment { 
static Object[] objects = { new Object(), new Object() }; 
static Thread[] threads = { new Thread(), new Thread() }; 


static Object[] arrayThrow() { 
throw new ArrayReferenceThrow() ; 
} 
static int indexThrow() { 
throw new IndexThrow() ; 
} 
static Thread rightThrow() { 
throw new RightHandSideThrow(); 
} 
static String name(Object q) { 
String sq = q.getClass().getName(); 
int k = sq.lastIndexOf('.'); 
return (k < 0) ? sq : sq.substring(k+1); 
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static void testFour(Object[] x, int j, Object y) { 

String sx = x == null ? "null" : name(x[0]) + "s"; 

String sy = name(y); 

System.out.println(); 

try { 
System.out.print (sx + "[throw]=throw => "); 
x[indexThrow()] = rightThrow(); 
System.out.println("Okay!"); 

} catch (Throwable e) { System.out.printin(name(e) ); 


try { 
System.out.print (sx + "[throw]=" + sy + " => "); 
x[indexThrow()] = y; 


System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e) ); 


try { 
System.out.print(sx + "[" + 3 + "J=throw => "); 
x[j] = rightThrow(); 


System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e) ); 


try { 
System.out.print(sx + "([" + j + "]="_+ sy + " => 
x(3] = y; 


System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e) ); 


public static void main(String[] args) { 


try { 
System.out.print ("throw[throw]=throw => "); 
arrayThrow() [indexThrow()] = rightThrow(); 
System.out.println("Okay!"); 
} catch (Throwable e) System.out.printiln (name (e) ); 
try { 
System.out.print ("throw[throw]=Thread => "); 
arrayThrow() [indexThrow()] = new Thread(); 
System.out.println("Okay!"); 
} catch (Throwable e) System.out.printiln (name (e) ); 
try { 
System.out.print ("throw[1]=throw => "); 
arrayThrow()[1] = rightThrow(); 


System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e) ); 
try { 
System.out.print ("throw[1]=Thread => "); 
arrayThrow() [1] = new Thread(); 
System.out.println("Okay!"); 


} catch (Throwable e) { System.out.printin(name(e) ); 


testFour(null, 1, new StringBuffer()); 
testFour(null, 9, new Thread()); 
testFour(objects, 1, new StringBuffer ()); 
testFour(objects, 1, new Thread()); 
testFour(objects, 9, new StringBuffer ()); 
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} 


} 


} 


"); 
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testFour (objects, 
testFour (threads, 
testFour (threads, 
testFour (threads, 
testFour (threads, 


This program produces the output: 


s 


s s 


TO: SO i Ee. te 
s 


s 


new 
new 
new 
new 
new 


Thread ()); 
StringBuffer ()); 
Thread ()); 
StringBuffer ()); 
Thread ()); 
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throw[throw]=throw => ArrayReferenceThrow 
throw[throw]=Thread => ArrayReferenceThrow 
throw[1]=throw => ArrayReferenceThrow 
throw[1]=Thread => ArrayReferenceThrow 


null[throw]=throw => IndexThrow 
null[throw]=StringBuffer => IndexThrow 
null[1l]=throw => RightHandSideThrow 
null[1]=StringBuffer => NullPointerException 


null[throw]=throw => IndexThrow 
null[throw]=Thread => IndexThrow 
null[9]=throw => RightHandSideThrow 
null[9]=Thread => NullPointerException 


Objects[throw]=throw => IndexThrow 
Objects [throw]=StringBuffer => IndexThrow 
Objects[1]=throw => RightHandSideThrow 
Objects[1]=StringBuffer => Okay! 


Objects[throw]=throw => IndexThrow 
Objects[throw]=Thread => IndexThrow 
Objects[1l]=throw => RightHandSideThrow 
Objects[1]=Thread => Okay! 


Objects [throw]=throw => IndexThrow 

Objects [throw]=StringBuffer => IndexThrow 
Objects[9]=throw => RightHandSideThrow 
Objects[9]=StringBuffer => ArrayIndexOutOfBoundsException 


Objects[throw]=throw => IndexThrow 
Objects[throw]=Thread => IndexThrow 
Objects[9]=throw => RightHandSideThrow 
Objects[9]=Thread => ArrayIndexOutOfBoundsException 


3 


[Threads [throw]=throw => IndexThrow 

Threads [throw]=StringBuffer => IndexThrow 
Threads [1]=throw => RightHandSideThrow 

Threads [1]=StringBuffer => ArrayStoreException 


3 


3 


3 


3 


Threads [throw]=throw => IndexThrow 
[Threads [throw]=Thread => IndexThrow 
Threads[1]=throw => RightHandSideThrow 
[Threads [1]=Thread => Okay! 


3 


3 


3 


3 


[Threads [throw]=throw => IndexThrow 

Threads [throw]=StringBuffer => IndexThrow 

Threads [9]=throw => RightHandSideThrow 

Threads [9]=StringBuffer => ArrayIndexOutOfBoundsException 


3 


3 


3 


3 


[Threads [throw]=throw => IndexThrow 

hreads [throw]=Thread => IndexThrow 

Threads [9]=throw => RightHandSideThrow 

Threads [9]=Thread => ArrayIndexOutOfBoundsException 


3 
| 


3 


3 
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The most interesting case of the lot is thirteenth from the end: 
Threads [1]=StringBuffer => ArrayStoreException 


which indicates that the attempt to store a reference to a StringBuffer into an array whose 
components are of type Thread throws an ArrayStoreException. The code is type- 
correct at compile time: the assignment has a left-hand side of type Object [] and a right- 
hand side of type Object. At run time, the first actual argument to method testFour is a 
reference to an instance of "array of Thread" and the third actual argument is a reference 
to an instance of class StringBuffer. 


15.26.2 Compound Assignment Operators 


A compound assignment expression of the form £1 op= £2 is equivalent to £1 


(T) ((E1) op (E2)), where T is the type of £1, except that £1 is evaluated 


only once. 


For example, the following code is correct: 


short x = 3; 
x += 4.6; 


and results in x having the value 7 because it is equivalent to: 


short x = 3; 
x = (short) (x + 4.6); 


At run time, the expression is evaluated in one of two ways. 


If the left-hand operand expression is not an array access expression, then: 


First, the left-hand operand is evaluated to produce a variable. If this evaluation 
completes abruptly, then the assignment expression completes abruptly for the 
same reason; the right-hand operand is not evaluated and no assignment occurs. 


Otherwise, the value of the left-hand operand is saved and then the right-hand 
operand is evaluated. If this evaluation completes abruptly, then the assignment 
expression completes abruptly for the same reason and no assignment occurs. 


Otherwise, the saved value of the left-hand variable and the value of the 
right-hand operand are used to perform the binary operation indicated by 
the compound assignment operator. If this operation completes abruptly, then 
the assignment expression completes abruptly for the same reason and no 
assignment occurs. 


Otherwise, the result of the binary operation is converted to the type of the left- 
hand variable, subjected to value set conversion (§5.1.13) to the appropriate 
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standard value set (not an extended-exponent value set), and the result of the 
conversion is stored into the variable. 


If the left-hand operand expression is an array access expression (§15.10.3), then: 


¢ First, the array reference subexpression of the left-hand operand array access 
expression is evaluated. If this evaluation completes abruptly, then the 
assignment expression completes abruptly for the same reason; the index 
subexpression (of the left-hand operand array access expression) and the right- 
hand operand are not evaluated and no assignment occurs. 


¢ Otherwise, the index subexpression of the left-hand operand array access 
expression is evaluated. If this evaluation completes abruptly, then the 
assignment expression completes abruptly for the same reason and the right-hand 
operand is not evaluated and no assignment occurs. 


¢ Otherwise, if the value of the array reference subexpression is null, then no 
assignment occurs and a NullPointerException is thrown. 


¢ Otherwise, the value of the array reference subexpression indeed refers to an 
array. If the value of the index subexpression is less than zero, or greater 
than or equal to the Length of the array, then no assignment occurs and an 
ArrayIndexOutOfBoundsException Is thrown. 


¢ Otherwise, the value of the index subexpression is used to select a component 
of the array referred to by the value of the array reference subexpression. The 
value of this component is saved and then the right-hand operand is evaluated. 
If this evaluation completes abruptly, then the assignment expression completes 
abruptly for the same reason and no assignment occurs. 


For a simple assignment operator, the evaluation of the right-hand operand occurs before 
the checks of the array reference subexpression and the index subexpression, but for a 
compound assignment operator, the evaluation of the right-hand operand occurs after 
these checks. 


¢ Otherwise, consider the array component selected in the previous step, whose 
value was saved. This component is a variable; call its type s. Also, let r be 
the type of the left-hand operand of the assignment operator as determined at 
compile time. 


— If ris a primitive type, then s is necessarily the same as T. 


The saved value of the array component and the value of the right-hand 
operand are used to perform the binary operation indicated by the compound 
assignment operator. 
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If this operation completes abruptly (the only possibility is an integer division 
by zero - see §15.17.2), then the assignment expression completes abruptly for 


Assignment Operators 


the same reason and no assignment occurs. 


Otherwise, the result of the binary operation is converted to the type of the 
selected array component, subjected to value set conversion (§5.1.13) to the 
appropriate standard value set (not an extended-exponent value set), and the 


result of the conversion is stored into the array component. 


— If ris a reference type, then it must be string. Because class String is a 


final class, s must also be String. 


Therefore the run-time check that is sometimes required for the simple assignment 


operator is never requir 


The saved value of the array component and the value of the right-hand 
operand are used to perform the binary operation (string concatenation) 
indicated by the compound assignment operator (which is necessarily +=). If 
this operation completes abruptly, then the assignment expression completes 


ed for a compound assignment operator. 


abruptly for the same reason and no assignment occurs. 


Otherwise, the string result of the binary operation is stored into the array 


component. 


Example 15.26.2-1. Compound Assignment To An Array Component 


class ArrayReferen 
class IndexThrow 
class RightHandSid 


class IllustrateCo 
static String[ 
static double[ 


static String[ 
throw new 


static double[ 
throw new 


static int ind 
throw new 


static String 
throw new 


static double 
throw new 


ceThrow extends RuntimeException { } 
extends RuntimeException { } 
eThrow extends RuntimeException { } 


mpoundArrayAssignment { 
strings = { "Simon", "Garfunkel" }; 


doubles = { Math.E, Math.PI }; 


stringsThrow() { 
ArrayReferenceThrow(); 


doublesThrow() { 
ArrayReferenceThrow(); 


exThrow() { 


ndexThrow(); 


stringThrow() { 
RightHandSideThrow () ; 


doubleThrow() { 
RightHandSideThrow () ; 
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static String name(Object q) { 
String sq = q.getClass().getName() ; 
int k = sq.lastIndexOf('.'); 
return (k < 0) ? sq: sq.substring(k+1); 


static void testEight (String[] x, double[] z, int j) { 


String sx = (x == null) ? "null" : "Strings"; 
String sz = (z == null) ? "null" : "doubles"; 
System.out.println(); 
try { 
System.out.print (sx + "[throw]+=throw => "); 
x[indexThrow()] += stringThrow(); 


System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 


try { 
System.out.print(sz + "[throw]+=throw => "); 
z[indexThrow()] += doubleThrow() ; 


System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 


try { 
System.out.print(sx + "[throw]+=\"heh\" => "); 
x[indexThrow()] += "heh"; 


System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 


try { 
System.out.print(sz + "[throw]+=12345 => "); 
z[indexThrow()] += 12345; 


System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 
try { 
System.out.print(sx + "[" + 3 + "]+=throw => "); 
x[j] += stringThrow(); 
System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 
try { 
System.out.print(sz + "[" + 3 + "]+=throw => "); 
z[j] += doubleThrow() ; 
System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 
try { 
System.out.print(sx + "([" + j + "]+=\"heh\" => "); 
x[j] += "heh"; 
System.out.println("Okay!"); 


} catch (Throwable e) { System.out.printin(name(e)); } 
try { 
System.out.print(sz + "[" + 3 + "]+=12345 => "); 


z{j] += 12345; 
System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 


public static void main(String[] args) { 
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try { 
System.out.print ("throw[throw]+=throw => "); 
stringsThrow() [indexThrow()] += stringThrow(); 


System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 


try { 
System.out.print ("throw[throw]+=throw => "); 
doublesThrow() [indexThrow()] += doubleThrow() ; 


System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 


try { 
System.out.print ("throw[throw]+=\"heh\" => "); 
stringsThrow() [indexThrow()] += "heh"; 
System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 
try { 
System.out.print ("throw[throw]+=12345 => "); 
doublesThrow() [indexThrow()] += 12345; 


System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 


try { 
System.out.print ("throw[1]+=throw => "); 
stringsThrow() [1] += stringThrow(); 


System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 
try { 
System.out.print ("throw[1]+=throw => "); 
doublesThrow() [1] += doubleThrow(); 
System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 
try { 
System.out.print ("throw[1]+=\"heh\" => "); 
stringsThrow() [1] += "heh"; 
System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 
try { 
System.out.print ("throw[1]+=12345 => "); 
doublesThrow() [1] += 12345; 
System.out.println("Okay!"); 
} catch (Throwable e) { System.out.printin(name(e)); } 
testEight (null, null, 1); 
testEight (null, null, 9); 
testEight (strings, doubles, 1); 
testEight (strings, doubles, 9); 


This program produces the output: 
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throw[throw]+=thro 
throw[throw]+=thro 
throw[throw] +="heh 
throw[throw] +=1234 
throw[1]+=throw => 
throw[1]+=throw => 
throw[1]+="heh" => 
throw[1]+=12345 => 
nul throw] +=throw 
nul throw] +=throw 
nul throw]+="heh" 
null [throw] +=12345 
nul 1]+=throw => 
nul 1]+=throw => 
nul 1]+="heh" => 
nul 1]+=12345 => 
nul throw] +=throw 
nul throw] +=throw 
nul throw]+="heh" 
null [throw] +=12345 
nul 

null[9]+=throw => 
null[9]+="heh" => 
nul 


Strings [throw]+=th 
doubles [throw] +=th 
Strings [throw]+="h 
doubles [throw] +=12 


Strings 
doubles 
Strings 
doubles 


1]+=throw 
1]+=throw 
1]+="heh" 
1]+=12345 


Strings [throw]+=th 
doubles [throw] +=th 
Strings [throw]+="h 
doubles [throw] +=12 


Strings 
doubles 
Strings 
doubles 


The most interesting cases of the lot are eleventh and twelfth from the end: 


w => ArrayReferenceThrow 
w => ArrayReferenceThrow 
"=> ArrayReferenceThrow 
5 => ArrayReferenceThrow 
ArrayReferenceThrow 
ArrayReferenceThrow 
ArrayReferenceThrow 
ArrayReferenceThrow 


=> IndexThrow 

=> IndexThrow 

=> IndexThrow 

=> IndexThrow 
NullPointerException 
NullPointerException 
NullPointerException 
NullPointerException 


=> IndexThrow 
=> IndexThrow 
=> IndexThrow 
=> IndexThrow 


9]+=throw => NullPointerException 


NullPointerException 
NullPointerException 


9]+=12345 => NullPointerException 


row => IndexThrow 
row => IndexThrow 
eh" => IndexThrow 
345 => IndexThrow 


=> RightHandSideThrow 
=> RightHandSideThrow 


=> Okay! 
=> Okay! 
row => IndexThrow 
row => IndexThrow 
eh" => IndexThrow 
345 => IndexThrow 


9]+=throw => ArrayIndexOutOfBoundsException 
9]+=throw => ArrayIndexOutOfBoundsException 
9]+="heh" => ArrayIndexOutOfBoundsException 
9]+=12345 => ArrayIndexOutOfBoundsException 


Strings[1]+=throw => RightHandSideThrow 
doubles[1]+=throw => RightHandSideThrow 


EXPRESSIONS 


They are the cases where a right-hand side that throws an exception actually gets to throw 
the exception; moreover, they are the only such cases in the lot. This demonstrates that 


EXPRESSIONS Lambda Expressions 


the evaluation of the right-hand operand indeed occurs after the checks for a null array 
reference value and an out-of-bounds index value. 


Example 15.26.2-2. Value Of Left-Hand Side Of Compound Assignment Is Saved Before 
Evaluation Of Right-Hand Side 


class Test { 
public static void main(String[] args) { 
int k = 1; 
int[] a= {1}; 
k += (k = 4) * (k + 2); 
a[0] += (a[0] = 4) * (a[0] + 2); 
System.out.printin("k==" + k + " and a[0]==" + a[0]); 


} 
This program produces the output: 
k==25 and a[0]==25 


The value 1 of k is saved by the compound assignment operator += before its right-hand 
operand (k = 4) * (k + 2) is evaluated. Evaluation of this right-hand operand then 
assigns 4 to k, calculates the value 6 fork + 2, and then multiplies 4 by 6 to get 24. This 
is added to the saved value 1 to get 25, which is then stored into k by the += operator. An 
identical analysis applies to the case that uses a[0]. 


In short, the statements: 


k += (k = 4) * (k + 2); 
a[0] += (a[0] = 4) * (a[0] + 2); 


behave in exactly the same manner as the statements: 


k =k + (k = 4) * (k + 2); 
af0] = a[0] + (af[0] = 4) * (a[0] + 2); 


15.27 Lambda Expressions 


A lambda expression is like a method: it provides a list of formal parameters and 
a body - an expression or block - expressed in terms of those parameters. 


LambdaExpression: 
LambdaParameters -> LambdaBody 


Lambda expressions are always poly expressions ($15.2). 
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It is a compile-time error if a lambda expression occurs in a program in someplace 
other than an assignment context (§5.2), an invocation context (§5.3), or a casting 


context (§5.5). 


Evaluation of a lambda expression produces an instance of a functional interface 
($9.8). Lambda expression evaluation does not cause the execution of the 
expression's body; instead, this may occur at a later time when an appropriate 


method of the functional interface is invoked. 


Here are some examples of lambda expressions: 


(jyc=e AF // No parameters; 
() -> 42 // No parameters, 
() -> null // No parameters, 
() -> { return 42; } // No parameters, 
() 


-> { System.gc(); } // No parameters, 


EXPRESSIONS 


result is void 


expression 
expression 
block body 
void block 


body 
body 
with return 
body 


() -> { // Complex block body with returns 
if (true) return 12; 
else { 
int result = 15; 
for (int i = 1; i < 10; i++) 


result *= i; 
return result; 


(int x) -> x41 // Single declared-type parameter 
(int x) -> { return x+1l; } // Single declared-type parameter 
(x) -> x+l1 // Single inferred-type parameter 
x —-> x41 // Parentheses optional for 

// single inferred-type parameter 
(String s) -> s.length() // Single declared-type parameter 
(Thread t) -> { t.start(); } // Single declared-type parameter 
s -> s.length() // Single inferred-type parameter 
t -> { t.start(); } // Single inferred-type parameter 


int x, int y) -> xty // Multiple declared-type parameters 


( 

(xp oy) > oxy // Multiple inferred-type parameters 

(x, int y) -> xty // Tllegal: can't mix inferred and declared types 
(x, final y) -> xty // Illegal: no modifiers with inferred types 


This syntax has the advantage of minimizing bracket noise around simple lambda 
expressions, which is especially beneficial when a lambda expression is an argument to 
a method, or when the body is another lambda expression. It also clearly distinguishes 
between its expression and statement forms, which avoids ambiguities or over-reliance on 
';' tokens. When some extra bracketing is needed to visually distinguish either the full 
lambda expression or its body expression, parentheses are naturally supported (just as in 


other cases in which operator precedence is unclear). 


EXPRESSIONS Lambda Expressions 


The syntax has some parsing challenges. The Java programming language has always 
required arbitrary lookahead to distinguish between types and expressions after a'(' token: 
what follows may be a cast or a parenthesized expression. This was made worse when 
generics reused the binary operators '<' and '>' in types. Lambda expressions introduce a 
new possibility: the tokens following '(' may describe a type, an expression, or a lambda 
parameter list. Some tokens immediately indicate a parameter list (annotations, final); 
in other cases there are certain patterns that must be interpreted as parameter lists (two 
names in a row, a',' not nested inside of '<' and '>'); and sometimes, the decision cannot 
be made until a '->' is encountered after a')'. The simplest way to think of how this might 
be efficiently parsed is with a state machine: each state represents a subset of possible 
interpretations (type, expression, or parameters), and when the machine transitions to a state 
in which the set is a singleton, the parser knows which case it is. This does not map very 
elegantly to a fixed-lookahead grammar, however. 


There is no special nullary form: a lambda expression with zero arguments is expressed as 
() -> ....The obvious special-case syntax, -> ..., does not work because it introduces 
an ambiguity between argument lists and casts: (x) -> 


Lambda expressions cannot declare type parameters. While it would make sense 
semantically to do so, the natural syntax (preceding the parameter list with a type parameter 
list) introduces messy ambiguities. For example, consider: 


foo( (x) <y, z2> (w) -> Vv) 


This could be an invocation of foo with one argument (a generic lambda cast to type x), 
or it could be an invocation of £00 with two arguments, both the results of comparisons, 
the second comparing z with a lambda expression. (Strictly speaking, a lambda expression 
is meaningless as an operand to the relational operator >, but that is a tenuous assumption 
on which to build the grammar.) 


There is a precedent for ambiguity resolution involving casts, which essentially prohibits 
the use of — and + following a non-primitive cast (§15.15), but to extend that approach to 
generic lambdas would involve invasive changes to the grammar. 


15.27.1 Lambda Parameters 


The formal parameters of a lambda expression, if any, are specified by either a 
parenthesized list of comma-separated parameter specifiers or a parenthesized list 
of comma-separated identifiers. In a list of parameter specifiers, each parameter 
specifier consists of optional modifiers, then a type (or var), then an identifier that 
specifies the name of the parameter. In a list of identifiers, each identifier specifies 
the name of the parameter. 


If a lambda expression has no formal parameters, then an empty pair of parentheses 
appears before the -> and the lambda body. 
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If a lambda expression has exactly one formal parameter, and the parameter is 
specified by an identifier instead of a parameter specifier, then the parentheses 
around the identifier may be elided. 


LambdaParameters: 
( [LambdaParameterList] ) 
Identifier 


LambdaParameterList: 
LambdaParameter {, LambdaParameter} 
Identifier {, Identifier} 


LambdaParameter: 
{VariableModifier} LambdaParameterType VariableDeclaratorId 
VariableArityParameter 


LambdaParameterType: 
UnannType 


var 
The following productions from §8.4.1, §8.3, and §4.3 are shown here for convenience: 


VariableArityParameter: 
{VariableModifier} UnannType {Annotation} . . . Identifier 


VariableModifier: 
Annotation 
final 


VariableDeclaratorld: 
Identifier [Dims] 


Dims: 
{Annotation} [| ] {{Annotation} [ ]} 


A formal parameter of a lambda expression may be declared final, or annotated, 
only if specified by a parameter specifier. If a formal parameter is specified by an 
identifier instead, then the formal parameter is not final and has no annotations. 


A formal parameter of a lambda expression may be a variable arity parameter, 
indicated by an ellipsis following the type in a parameter specifier. At most one 
variable arity parameter is permitted for a lambda expression. It is a compile- 
time error if a variable arity parameter appears anywhere in the list of parameter 
specifiers except the last position. 


EXPRESSIONS Lambda Expressions 


Each formal parameter of a lambda expression has either an inferred type or a 
declared type: 


If a formal parameter is specified either by a parameter specifier that uses var, 
or by an identifier instead of a parameter specifier, then the formal parameter has 
an inferred type. The type is inferred from the functional interface type targeted 
by the lambda expression (§15.27.3). 


If a formal parameter is specified by a parameter specifier that does not use var, 
then the formal parameter has a declared type. The declared type is determined 
as follows: 


— If the formal parameter is not a variable arity parameter, then the declared 
type is denoted by UnannType if no bracket pairs appear in UnannType and 
VariableDeclaratorld, and specified by §10.2 otherwise. 


— If the formal parameter is a variable arity parameter, then the declared type is 
an array type specified by $10.2. 


No distinction is made between the following lambda parameter lists: 


(int... x) -> BODY 
(int[] x) -> BODY 


Either can be used, whether the functional interface's abstract method is fixed arity or 
variable arity. (This is consistent with the rules for method overriding.) Since lambda 
expressions are never directly invoked, using int... for the formal parameter where the 
functional interface uses int [] can have no impact on the surrounding program. In a 
lambda body, a variable arity parameter is treated just like an array-typed parameter. 


A lambda expression where all the formal parameters have declared types is said 
to be explicitly typed. A lambda expression where all the formal parameters have 
inferred types is said to be implicitly typed. A lambda expression with no formal 
parameters is explicitly typed. 


If a lambda expression is implicitly typed, then its lambda body is interpreted according 
to the context in which it appears. Specifically, the types of expressions in the body, and 
the checked exceptions thrown by the body, and the type correctness of code in the body 
all depend on the types inferred for the formal parameters. This implies that inference of 
formal parameter types must occur "before" attempting to type-check the lambda body. 


It is a compile-time error if a lambda expression declares a formal parameter with 
a declared type and a formal parameter with an inferred type. 


This rule prevents a mix of inferred and declared types in the formal parameters, such as 
(x, int y) -> BODYor (var x, int y) -> BoDy. Note that if all the formal parameters 
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have inferred types, the grammar prevents a mix of identifiers and var parameter specifiers, 
such as (x, var y) -> BODYor (var x, y) -> BODY. 


The rules for annotation modifiers on a formal parameter declaration are specified 
in §9.7.4 and 89.7.5. 


It is acompile-time error if final appears more than once as a modifier for a formal 
parameter declaration. 


It is a compile-time error if the LambdaParameterType of a formal parameter is 
var and the VariableDeclaratorld of the same formal parameter has one or more 
bracket pairs. 


The scope and shadowing of a formal parameter declaration is specified in §6.3 
and §6.4. 


It is a compile-time error for a lambda expression to declare two formal parameters 
with the same name. (That is, their declarations mention the same Identifier.) 


In Java SE 8, the use of _ as the name of a lambda parameter was forbidden, and its use 
discouraged as the name for other kinds of variable (§4.12.3). As of Java SE 9, _ is a 
keyword (§3.9) so it cannot be used as a variable name in any context. 


It is a compile-time error if a formal parameter that is declared final is assigned 
to within the body of the lambda expression. 


When the lambda expression is invoked (via a method invocation expression 
($15.12)), the values of the actual argument expressions initialize newly created 
parameter variables, each of the declared or inferred type, before execution of the 
lambda body. The /dentifier that appears in the LambdaParameter or directly in 
the LambdaParameterList or LambdaParameters may be used as a simple name 
in the lambda body to refer to the formal parameter. 


A lambda expression's formal parameter of type float always contains an element 
of the float value set (§4.2.3); similarly, a lambda expression's formal parameter of 
type double always contains an element of the double value set. It is not permitted 
for a lambda expression's formal parameter of type float to contain an element of 
the float-extended-exponent value set that is not also an element of the float value 
set, nor for a lambda expression's formal parameter of type double to contain an 
element of the double-extended-exponent value set that is not also an element of 
the double value set. 


EXPRESSIONS Lambda Expressions 


15.27.2 Lambda Body 


A lambda body is either a single expression or a block (§ 14.2). Like a method body, 
a lambda body describes code that will be executed whenever an invocation occurs. 


LambdaBody: 
Expression 
Block 


Unlike code appearing in anonymous class declarations, the meaning of names 
and the this and super keywords appearing in a lambda body, along with the 
accessibility of referenced declarations, are the same as in the surrounding context 
(except that lambda parameters introduce new names). 


The transparency of this (both explicit and implicit) in the body of a lambda expression 
- that is, treating it the same as in the surrounding context - allows more flexibility for 
implementations, and prevents the meaning of unqualified names in the body from being 
dependent on overload resolution. 


Practically speaking, it is unusual for a lambda expression to need to talk about itself (either 
to call itself recursively or to invoke its other methods), while it is more common to want 
to use names to refer to things in the enclosing class that would otherwise be shadowed 
(this, toString () ). If it is necessary for a lambda expression to refer to itself (as if via 
this), a method reference or an anonymous inner class should be used instead. 


A block lambda body is void-compatible if every return statement in the block has 
the form return;. 


A block lambda body is value-compatible if it cannot complete normally ($14.21) 
and every return statement in the block has the form return Expression;. 


It is a compile-time error if a block lambda body is neither void-compatible nor 
value-compatible. 


In a value-compatible block lambda body, the result expressions are any 
expressions that may produce an invocation's value. Specifically, for each 
statement of the form return Expression ; contained by the body, the Expression 
is aresult expression. 


The following lambda bodies are void-compatible: 


() -> {} 
() -> { System.out.println("done"); } 


These are value-compatible: 
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() -> { return "done"; } 
() -> { if (...) return 1; else return 0; } 


These are both: 


() -> { throw new RuntimeException(); } 
() -> { while (true); } 


This is neither: 
() -> { if (...) return "done"; System.out.println("done"); } 


The handling of void/value-compatible and the meaning of names in the body jointly serve 
to minimize the dependency on a particular target type in the given context, which is 
useful both for implementations and for programmer comprehension. While expressions 
can be assigned different types during overload resolution depending on the target type, the 
meaning of unqualified names and the basic structure of the lambda body do not change. 


Note that the void/value-compatible definition is not a strictly structural property: "can 
complete normally" depends on the values of constant expressions, and these may include 
names that reference constant variables. 


Any local variable, formal parameter, or exception parameter used but not declared 
in a lambda expression must either be declared final or be effectively final 
($4.12.4), or a compile-time error occurs where the use is attempted. 


Any local variable used but not declared in a lambda body must be definitely 
assigned (§16 (Definite Assignment)) before the lambda body, or a compile-time 
error occurs. 


Similar rules on variable use apply in the body of an inner class (§8.1.3). The restriction to 
effectively final variables prohibits access to dynamically-changing local variables, whose 
capture would likely introduce concurrency problems. Compared to the final restriction, 
it reduces the clerical burden on programmers. 


The restriction to effectively final variables includes standard loop variables, but not 
enhanced-for loop variables, which are treated as distinct for each iteration of the loop 
(§14.14.2). 


The following lambda bodies demonstrate use of effectively final variables. 


void ml(int x) { 

int y = 1; 

foo(() -> xty); 

// Legal: x and y are both effectively final. 
} 


void m2(int x) { 
int y; 
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yl; 
foo(() -> x+y); 
// Legal: x and y are both effectively final. 


void m3(int x) { 
int y; 
LE Cewed = 1G 
foo(() —> xty); 
// Tllegal: y is effectively final, but not definitely assigned. 


void m4(int x) { 


int y; 
if (...) y = 1; else y = 2; 
foo(() -—> xty); 


// Legal: x and y are both effectively final. 


void m5(int x) { 


int y; 
LE Cy gy Vy Sods 
y = 2; 
foo(() -—> xty); 


// Tllegal: y is not effectively final. 


void m6(int x) { 
foo(() -> x+1); 
x++; 
// Tllegal: x is not effectively final. 


void m7(int x) { 
foo(() —-> x=1); 
// Tllegal: x is not effectively final. 


void m8() { 
SE eg 
foo(() —> y=1); 
// Tllegal: y is not definitely assigned before the lambda. 


void m9(String[] arr) { 
for (String s : arr) { 
foo(() -> s); 


// Legal: s is effectively final 
// (it is a new variable on each iteration) 


void m10(String[] arr) { 
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for (int i = 0; i < arr.length; i++) { 
foo(() -> arrfi]); 
// Tllegal: i is not effectively final 
// (it is not final, and is incremented) 


15.27.3 Type of a Lambda Expression 


A lambda expression is compatible in an assignment context, invocation context, 
or casting context with a target type rif ris a functional interface type ($9.8) and 
the expression is congruent with the function type of the ground target type derived 
from T. 


The ground target type is derived from T as follows: 


If r is a wildcard-parameterized functional interface type and the lambda 
expression is explicitly typed, then the ground target type is inferred as described 
in §18.5.3. 


If r is a wildcard-parameterized functional interface type and the lambda 
expression is implicitly typed, then the ground target type is the non-wildcard 
parameterization (§9.9) of r. 


Otherwise, the ground target type is T. 


A lambda expression is congruent with a function type if all of the following are 
true: 


The function type has no type parameters. 


The number of lambda parameters is the same as the number of parameter types 
of the function type. 


If the lambda expression is explicitly typed, its formal parameter types are the 
same as the parameter types of the function type. 


If the lambda parameters are assumed to have the same types as the function 
type's parameter types, then: 


— If the function type's result is void, the lambda body is either a statement 
expression ($14.8) or a void-compatible block. 


— If the function type's result is a (non-void) type R, then either (i) the lambda 
body is an expression that is compatible with R in an assignment context, or 
(ii) the lambda body is a value-compatible block, and each result expression 
($15.27.2) is compatible with R in an assignment context. 


EXPRESSIONS Lambda Expressions 


If a lambda expression is compatible with a target type 1, then the type of the 
expression, u, is the ground target type derived from r. 


It is a compile-time error if any class or interface mentioned by either vu or the 
function type of vis not accessible ($6.6) from the class or interface in which the 
lambda expression appears. 


For each non-static member method m of u, if the function type of u has a 
subsignature of the signature of m, then a notional method whose method type is the 
function type of vis deemed to override m, and any compile-time error or unchecked 
warning specified in §8.4.8.3 may occur. 


A checked exception that can be thrown in the body of the lambda expression may 
cause a compile-time error, as specified in §11.2.3. 


The parameter types of explicitly typed lambdas are required to exactly match those of 
the function type. While it would be possible to be more flexible - allow boxing or 
contravariance, for example - this kind of generality seems unnecessary, and is inconsistent 
with the way overriding works in class declarations. A programmer ought to know exactly 
what function type is being targeted when writing a lambda expression, so he should thus 
know exactly what signature must be overridden. (In contrast, this is not the case for 
method references, and so more flexibility is allowed when they are used.) In addition, 
more flexibility with parameter types would add to the complexity of type inference and 
overload resolution. 


Note that while boxing is not allowed in a strict invocation context, boxing of lambda 
result expressions is always allowed - that is, the result expression appears in an assignment 
context, regardless of the context enclosing the lambda expression. However, if an 
explicitly typed lambda expression is an argument to an overloaded method, a method 
signature that avoids boxing or unboxing the lambda result is preferred by the most specific 
check (§15.12.2.5). 


If the body of a lambda is a statement expression (that is, an expression that would be 
allowed to stand alone as a statement), it is compatible with a void-producing function 
type; any result is simply discarded. So, for example, both of the following are legal: 


// Predicate has a boolean result 
java.util.function.Predicate<String> p = s -> list.add(s); 
// Consumer has a void result 
java.util.function.Consumer<String> c = s —> list.add(s); 


Generally speaking, a lambda of the form () -> expr, where expr is a statement expression, 
is interpreted as either () -> { return expr; } or () -> { expr; }, depending on the 
target type. 
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15.27.4 Run-Time Evaluation of Lambda Expressions 


At run time, evaluation of a lambda expression is similar to evaluation of a class 
instance creation expression, insofar as normal completion produces a reference 
to an object. Evaluation of a lambda expression is distinct from execution of the 
lambda body. 


Either a new instance of a class with the properties below is allocated and 
initialized, or an existing instance of a class with the properties below is referenced. 
If a new instance is to be created, but there is insufficient space to allocate the 
object, evaluation of the lambda expression completes abruptly by throwing an 


OutOfMemoryError. 


This implies that the identity of the result of evaluating a lambda expression (or, of 
serializing and deserializing a lambda expression) is unpredictable, and therefore identity- 
sensitive operations (such as reference equality (§15.21.3), object locking (§14.19), and 
the System.identityHashCode method) may produce different results in different 
implementations of the Java programming language, or even upon different lambda 
expression evaluations in the same implementation. 


The value of a lambda expression is a reference to an instance of a class with the 
following properties: 


¢ The class implements the targeted functional interface type and, if the target type 
is an intersection type, every other interface type mentioned in the intersection. 


¢ Where the lambda expression has type u, for each non-st atic member method 
mof U: 


If the function type of u has a subsignature of the signature of m, then the class 
declares a method that overrides m. The method's body has the effect of evaluating 
the lambda body, if it is an expression, or of executing the lambda body, if it is 
a block; if a result is expected, it is returned from the method. 


If the erasure of the type of a method being overridden differs in its signature 
from the erasure of the function type of vu, then before evaluating or executing the 
lambda body, the method's body checks that each argument value is an instance 
of a subclass or subinterface of the erasure of the corresponding parameter type 
in the function type of u; if not, a ClassCastException 1s thrown. 


¢ The class overrides no other methods of the targeted functional interface type 
or other interface types mentioned above, although it may override methods of 
the object class. 


These rules are meant to offer flexibility to implementations of the Java programming 
language, in that: 


EXPRESSIONS Constant Expressions 


¢ A new object need not be allocated on every evaluation. 


* Objects produced by different lambda expressions need not belong to different classes 
(if the bodies are identical, for example). 


¢ Every object produced by evaluation need not belong to the same class (captured local 
variables might be inlined, for example). 


¢ If an "existing instance" is available, it need not have been created at a previous lambda 
evaluation (it might have been allocated during the enclosing class's initialization, for 
example). 


If the targeted functional interface type is a subtype of java.io.Serializable, the 
resulting object will automatically be an instance of a serializable class. Making an object 
derived from a lambda expression serializable can have extra run time overhead and security 
implications, so lambda-derived objects are not required to be serializable "by default". 


15.28 Constant Expressions 


ConstantExpression: 
Expression 


A constant expression is an expression denoting a value of primitive type or a 
String that does not complete abruptly and is composed using only the following: 


Literals of primitive type and literals of type string (§3.10.1, §3.10.2, §3.10.3, 
§3.10.4, §3.10.5) 


Casts to primitive types and casts to type string ($15.16) 


The unary operators +, -, ~, and ! (but not ++ or --) (§15.15.3, §15.15.4, §15.15.5, 
§15.15.6) 


The multiplicative operators *, /, and % ($15.17) 

The additive operators + and - ($15.18) 

The shift operators <<, >>, and >>> ($15.19) 

The relational operators <, <=, >, and >= (but not instanceof) ($15.20) 
The equality operators == and != ($15.21) 

The bitwise and logical operators «, *, and | ($15.22) 


The conditional-and operator ss and the conditional-or operator || ($15.23, 
§15.24) 


The ternary conditional operator 2: ($15.25) 
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¢ Parenthesized expressions (§15.8.5) whose contained expression is a constant 
expression. 


¢ Simple names (§6.5.6.1) that refer to constant variables (§4.12.4). 


* Qualified names (§6.5.6.2) of the form TypeName . Identifier that refer to 
constant variables (§4.12.4). 


Constant expressions of type String are always "interned" so as to share unique 
instances, using the method string.intern. 


A constant expression is always treated as FP-strict ($15.4), even if it occurs in a 
context where a non-constant expression would not be considered to be FP-strict. 


Constant expressions are used as case labels in switch statements (§14.11) and have 
a special significance in assignment contexts (§5.2) and the initialization of a class or 
interface (§12.4.2). They may also govern the ability of a while, do, or for statement 
to complete normally ($14.21), and the type of a conditional operator ? : with numeric 
operands. 


Example 15.28-1. Constant Expressions 


true 

(short) (1*2*3*4*5*6) 

Integer.MAX_VALUE / 2 

2.0 * Math.PI 

"The integer " + Long.MAX_VALUE + " is mighty big." 


CHAPTER 16 


Definite Assignment 


Face local variable (§14.4) and every blank final field (§4.12.4, §8.3.1.2) must 
have a definitely assigned value when any access of its value occurs. 


An access to its value consists of the simple name of the variable (or, for a field, the 
simple name of the field qualified by this) occurring anywhere in an expression 
except as the left-hand operand of the simple assignment operator = (§15.26.1). 


For every access of a local variable or blank final field x, x must be definitely 
assigned before the access, or a compile-time error occurs. 


Similarly, every blank final variable must be assigned at most once; it must be 
definitely unassigned when an assignment to it occurs. 


Such an assignment is defined to occur if and only if either the simple name of the 
variable (or, for a field, its simple name qualified by this) occurs on the left hand 
side of an assignment operator. 


For every assignment to a blank final variable, the variable must be definitely 
unassigned before the assignment, or a compile-time error occurs. 


The remainder of this chapter is devoted to a precise explanation of the words 
"definitely assigned before" and "definitely unassigned before". 


The idea behind definite assignment is that an assignment to the local variable 
or blank final field must occur on every possible execution path to the access. 
Similarly, the idea behind definite unassignment is that no other assignment to the 
blank final variable is permitted to occur on any possible execution path to an 
assignment. 


The analysis takes into account the structure of statements and expressions; it also 
provides a special treatment of the expression operators !, &s, ||, and? :, and of 
boolean-valued constant expressions. 
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Except for the special treatment of the conditional boolean operators &«, ||, and 
2: and of boolean-valued constant expressions, the values of expressions are not 
taken into account in the flow analysis. 


Example 16-1. Definite Assignment Considers Structure of Statements and Expressions 


A Java compiler recognizes that k is definitely assigned before its access (as an argument 
of a method invocation) in the code: 


int k; 
if (v > 0 && (k = System.in.read()) >= 0) 
System.out.printin(k); 
because the access occurs only if the value of the expression: 


v > 0 && (k = System.in.read()) >= 0 


is true, and the value can be t rue only if the assignment to k is executed (more properly, 
evaluated). 


Similarly, a Java compiler will recognize that in the code: 


int k; 

while (true) { 
k = n; 
if (k >= 5) break; 
n= 6; 


} 
System.out.printin(k); 


the variable k is definitely assigned by the while statement because the condition 
expression true never has the value false, so only the break statement can cause the 
while statement to complete normally, and k is definitely assigned before the break 
statement. 


On the other hand, the code: 


int k; 

while (n < 4) { 
k = n; 
if (k >= 5) break; 
n = 6; 


} 
System.out.printin(k); /* k is not "definitely assigned" 
before this statement */ 


DEFINITE ASSIGNMENT 


must be rejected by a Java compiler, because in this case the while statement is not 
guaranteed to execute its body as far as the rules of definite assignment are concerned. 


Example 16-2. Definite Assignment Does Not Consider Values of Expressions 


A Java compiler must produce a compile-time error for the code: 


int k; 

int n = 5; 

if (n > 2) 
k = 3; 


System.out.printin(k); /* k is not "definitely assigned" 
before this statement */ 


even though the value of n is known at compile time, and in principle it can be known at 
compile time that the assignment to k will always be executed (more properly, evaluated). 
A Java compiler must operate according to the rules laid out in this section. The rules 
recognize only constant expressions; in this example, the expression n > 2 is not aconstant 
expression as defined in §15.28. 


As another example, a Java compiler will accept the code: 


void flow(boolean flag) { 


int k; 
if (flag) 
k = 3; 
else 
k = 4; 


System.out.printin(k); 


as far as definite assignment of k is concerned, because the rules outlined in this section 
allow it to tell that k is assigned no matter whether the flag is true or false. But the 
rules do not accept the variation: 


void flow(boolean flag) { 


int k; 

if (flag) 
k = 3; 

if (!flag) 
k = 4; 


System.out.printin(k); /* k is not "definitely assigned" 
before this statement */ 


and so compiling this program must cause a compile-time error to occur. 
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Example 16-3. Definite Unassignment 
A Java compiler will accept the code: 


void unflow(boolean flag) { 
final int k; 
if (flag) { 
k = 3; 
System.out.printin(k); 
} 
else { 
k = 4; 
System.out.printin(k); 


as far as definite unassignment of k is concerned, because the rules outlined in this section 
allow it to tell that k is assigned at most once (indeed, exactly once) no matter whether the 
flag is true or false. But the rules do not accept the variation: 


void unflow(boolean flag) { 
final int k; 
if (flag) { 
k= .3; 
System.out.printin(k); 
} 
if (!flag) { 
k = 4; 
System.out.printin(k); /* k is not "definitely unassigned" 
before this statement */ 


and so compiling this program must cause a compile-time error to occur. 


In order to precisely specify all the cases of definite assignment, the rules in this 
section define several technical terms: 


¢ whether a variable is definitely assigned before a statement or expression; 

¢ whether a variable is definitely unassigned before a statement or expression; 
¢ whether a variable is definitely assigned after a statement or expression; and 
¢ whether a variable is definitely unassigned after a statement or expression. 
For boolean-valued expressions, the last two are refined into four cases: 

¢ whether a variable is definitely assigned after the expression when true; 


¢ whether a variable is definitely unassigned after the expression when true; 
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¢ whether a variable is definitely assigned after the expression when false; and 
¢ whether a variable is definitely unassigned after the expression when false. 


Here, when true and when false refer to the value of the expression. 


For example, the local variable k is definitely assigned a value after evaluation of the 
expression: 


a && ((k=m) > 5) 


when the expression is true but not when the expression is false (because if a is false, 
then the assignment to k is not necessarily executed (more properly, evaluated)). 


The phrase "vis definitely assigned after x" (where vis a local variable and x is 
a statement or expression) means "Vv is definitely assigned after x if x completes 
normally". If x completes abruptly, the assignment need not have occurred, and the 
rules stated here take this into account. 


A peculiar consequence of this definition is that "Vis definitely assigned after break;" is 
always true! Because a break statement never completes normally, itis vacuously true that 
Vhas been assigned a value if the break statement completes normally. 


The statement "vis definitely unassigned after x" (where vis a variable and x is a 
statement or expression) means "Vv is definitely unassigned after x if x completes 
normally". 


An even more peculiar consequence of this definition is that "Vis definitely unassigned 
after break;" is always true! Because a break statement never completes normally, it 
is vacuously true that v has not been assigned a value if the break statement completes 
normally. (For that matter, it is also vacuously true that the moon is made of green cheese 
if the break statement completes normally.) 


In all, there are four possibilities for a variable v after a statement or expression 
has been executed: 


¢ vis definitely assigned and is not definitely unassigned. 

(The flow analysis rules prove that an assignment to v has occurred.) 
¢ vis definitely unassigned and is not definitely assigned. 

(The flow analysis rules prove that an assignment to v has not occurred.) 
¢ vis not definitely assigned and is not definitely unassigned. 

(The rules cannot prove whether or not an assignment to vhas occurred.) 


¢ vis definitely assigned and is definitely unassigned. 
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(It is impossible for the statement or expression to complete normally.) 


To shorten the rules, the customary abbreviation "iff" is used to mean "if and 
only if". We also use an abbreviation convention: if a rule contains one or 
more occurrences of "[un]assigned" then it stands for two rules, one with every 
occurrence of "[un]Jassigned" replaced by "definitely assigned" and one with every 
occurrence of "[un]assigned" replaced by "definitely unassigned". 


For example: 


* vis [unassigned after an empty statement iff it is [unJassigned before the empty 
statement. 


should be understood to stand for two rules: 


* vis definitely assigned after an empty statement iff it is definitely assigned before the 
empty statement. 


* vis definitely unassigned after an empty statement iff it is definitely unassigned before 
the empty statement. 


Throughout the rest of this chapter, we will, unless explicitly stated otherwise, 
write v to represent a local variable or blank fina1 field which is in scope ($6.3). 
Likewise, we will use a, b, c, and e to represent expressions, and s and rto represent 
statements. We will use the phrase "a is v" to mean that a is either the simple name 
of the variable v, or v’s simple name qualified by this (ignoring parentheses). We 
will use the phrase "a is not v’ to mean the negation of "a is v’. 


The definite unassignment analysis of loop statements raises a special problem. Consider 
the statement while (e) S.Inorderto determine whether Vis definitely unassigned within 
some subexpression of e, we need to determine whether Vv is definitely unassigned before 
e. One might argue, by analogy with the rule for definite assignment (§16.2.10), that Vis 
definitely unassigned before e iff it is definitely unassigned before the while statement. 
However, such a rule is inadequate for our purposes. If e evaluates to true, the statement 
S will be executed. Later, if Vis assigned by s, then in the following iteration(s) v will 
have already been assigned when e is evaluated. Under the rule suggested above, it would 
be possible to assign V multiple times, which is exactly what we have sought to avoid by 
introducing these rules. 


A revised rule would be: "Vis definitely unassigned before e iff it is definitely unassigned 
before the while statement and definitely unassigned after s". However, when we 
formulate the rule for Ss, we find: "Vis definitely unassigned before s iff it is definitely 
unassigned after e when true". This leads to a circularity. In effect, Vis definitely unassigned 
before the loop condition e only if it is unassigned after the loop as a whole! 


We break this vicious circle using a hypothetical analysis of the loop condition and body. 
For example, if we assume that vis definitely unassigned before e (regardless of whether v 
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really is definitely unassigned before e), and can then prove that v was definitely unassigned 
after e then we know that e does not assign Vv. This is stated more formally as: 


Assuming Vis definitely unassigned before e, vis definitely unassigned after e. 


Variations on the above analysis are used to define well founded definite unassignment 
tules for all loop statements in the Java programming language. 


16.1 Definite Assignment and Expressions 


16.1.1 Boolean Constant Expressions 


¢ vis [unJassigned after any constant expression ($15.28) whose value is true 
when false. 


¢ vis [un]assigned after any constant expression whose value is false when true. 


¢ vis [unJassigned after any constant expression whose value is true when true 
iff vis [unJassigned before the constant expression. 


¢ vis [unJassigned after any constant expression whose value is false when false 
iff vis [unJassigned before the constant expression. 


¢ v is [unJassigned after a boolean-valued constant expression e iff v is 
[unassigned after e when true and vis [unJassigned after e when false. 


This is equivalent to saying that vis [unJassigned after e iff vis [unJassigned before e. 


Because a constant expression whose value is true never has the value false, and a 
constant expression whose value is false never has the value t rue, the first two rules are 
vacuously satisfied. They are helpful in analyzing expressions involving the operators ¢& 
($16.1.2), | | ($16.1.3), ! (§16.1.4), and 2: (§16.1.5). 


16.1.2 Conditional-And Operator «<< 


¢ vis [unJassigned after a s& b (§15.23) when true iff vis [unJassigned after b 
when true. 


¢ vis [un]assigned after a «& b when false iff vis [unJassigned after a when false 
and vis [un]Jassigned after 5 when false. 


¢ vis [un]assigned before a iff vis [unJassigned before a && b. 


¢ vis [unjassigned before 5 iff vis [unJassigned after a when true. 
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¢ vis [unJassigned after a «x biff vis [unJassigned after a &s b when true and v 
is [unJassigned after a && b when false. 


16.1.3 Conditional-Or Operator | | 


¢ vis [unJassigned after a || 5 (§15.24) when true iff vis [unJassigned after a 
when true and vis [unJassigned after b when true. 


¢ vis [unJassigned after a | | b when false iff vis [un]assigned after b when false. 
¢ vis [unJassigned before a iff vis [unJassigned before a | | b. 
¢ vis [unjassigned before b iff vis [unJassigned after a when false. 


¢ vis [unJassigned after a || biff vis [unJassigned after a | | 5 when true and v 
is [unassigned after a | | b when false. 


16.1.4 Logical Complement Operator ! 


¢ vis [unJassigned after ! a (§15.15.6) when true iff vis [unJassigned after a when 
false. 


¢ vis [un]assigned after ! a when false iff vis [unJassigned after a when true. 
¢ vis [unJassigned before a iff vis [unJassigned before ! a. 


¢ vis [unJassigned after !a iff vis [unJassigned after !a when true and v is 
[unassigned after ! a when false. 


This is equivalent to saying that vis [unJassigned after ! a iff vis [un]assigned after a. 


16.1.5 Conditional Operator 2 : 


Suppose that b and c are boolean-valued expressions. 


¢ vis [unJassigned after a ? b : c ($15.25) when true iff vis [unassigned after b 
when true and vis [unJassigned after c when true. 


¢ vis [unJassigned after a ? b : c when false iff vis [unJassigned after b when 
false and vis [unassigned after c when false. 


¢ vis [unJassigned before a iff vis [unJassigned before a? b: c. 
¢ vis [unJassigned before 5 iff vis [unJassigned after a when true. 


¢ vis [unJassigned before c iff vis [unJassigned after a when false. 
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¢ vis [un]assigned after a ? b: ciff vis [unJassigned after a ? b : c when true 
and vis [unassigned after a ? b : c when false. 


16.1.6 Conditional Operator ? 


Suppose that b and c are expressions that are not boolean-valued. 


¢ vis [unJassigned after a ? b : c ($15.25) iff vis [unJassigned after b and vis 
[un]assigned after c. 


¢ vis [unJassigned before a iff vis [unJassigned before a? b: c. 
¢ vis [unJassigned before 5 iff vis [unJassigned after a when true. 


¢ vis [unJassigned before c iff vis [unJassigned after a when false. 


16.1.7 Other Expressions of Type boolean 


Suppose that e is an expression of type boolean and is not a boolean constant 
expression, logical complement expression ! a, conditional-and expression a && b, 
conditional-or expression a | | b, or conditional expression a? b: c. 


¢ vis [unJassigned after e when true iff vis [unJassigned after e. 


¢ vis [un]assigned after e when false iff vis [unJassigned after e. 


16.1.8 Assignment Expressions 


Consider an assignment expression a = b, a += b, a b,a*=b,a/=b,a%=b,a 
<<= b, a>>= b, a>>>=b, a &=b, a |= b, OF a *= b ($15.26). 


¢ vis definitely assigned after the assignment expression iff either: 
— alS V,or 
— vis definitely assigned after b. 


¢ vis definitely unassigned after the assignment expression iff a is not vand vis 
definitely unassigned after b. 


¢ vis [unJassigned before a iff vis [un]assigned before the assignment expression. 


¢ vis [un]assigned before 5 iff vis [unJassigned after a. 


Note that if a is Vand vis not definitely assigned before a compound assignment such as a 
&= b, then a compile-time error will necessarily occur. The first rule for definite assignment 
stated above includes the disjunct "a is v" even for compound assignment expressions, not 
just simple assignments, so that v will be considered to have been definitely assigned at 
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later points in the code. Including the disjunct "a is v" does not affect the binary decision 
as to whether a program is acceptable or will result in a compile-time error, but it affects 
how many different points in the code may be regarded as erroneous, and so in practice it 
can improve the quality of error reporting. A similar remark applies to the inclusion of the 
conjunct "a is not Vv" in the first rule for definite unassignment stated above. 


16.1.9 Operators ++ and -- 


¢ vis definitely assigned after ++a (§15.15.1), --a (§$15.15.2), at++ (§15.14.2), 
or a-- ($15.14.3) iff either a is v or vis definitely assigned after the operand 
expression. 


¢ vis definitely unassigned after ++a, --a, at++, or a-- iff a is not v and vis 
definitely unassigned after the operand expression. 


¢ vis [un]assigned before a iff vis [unJassigned before ++a, --a, at++, or a--. 


16.1.10 Other Expressions 


If an expression is not a boolean constant expression, and is not a preincrement 
expression ++a, predecrement expression --a, postincrement expression a++, 
postdecrement expression a--, logical complement expression ! a, conditional-and 
expression a && b, conditional-or expression a | | b, conditional expression a ? b : 
c, assignment expression, or lambda expression, then the following rules apply: 


¢ If the expression has no subexpressions, vis [unJassigned after the expression 
iff vis [unJassigned before the expression. 


This case applies to literals, names, this (both qualified and unqualified), unqualified 
class instance creation expressions with no arguments, array creation expressions with 
initializers that contain no expressions, superclass field access expressions, unqualified 
and type-qualified method invocation expressions with no arguments, superclass method 
invocation expressions with no arguments, and superclass and type-qualified method 
reference expressions. 


¢ If the expression has subexpressions, vis [un]assigned after the expression iff v 
is [unJassigned after its rightmost immediate subexpression. 


There is a piece of subtle reasoning behind the assertion that a variable v can be known 
to be definitely unassigned after a method invocation expression. Taken by itself, at face 
value and without qualification, such an assertion is not always true, because an invoked 
method can perform assignments. But it must be remembered that, for the purposes of the 
Java programming language, the concept of definite unassignment is applied only to blank 
final variables. If vis a blank final local variable, then only the method to which its 
declaration belongs can perform assignments to v. If vis a blank final field, then only 
a constructor or an initializer for the class containing the declaration for v can perform 
assignments to v; no method can perform assignments to v. Finally, explicit constructor 
invocations (§8.8.7.1) are handled specially (§16.9); although they are syntactically similar 
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to expression statements containing method invocations, they are not expression statements 
and therefore the rules of this section do not apply to explicit constructor invocations. 


If an expression is a lambda expression, then the following rules apply: 


vis [unJassigned after the expression iff vis [un]assigned before the expression. 


vis definitely assigned before the expression or block that is the lambda body 
($15.27.2) iff vis definitely assigned before the lambda expression. 


No rule allows v to be definitely unassigned before a lambda body. This is by design: 
a variable that was definitely unassigned before the lambda body may end up being 
assigned to later on, so we cannot conclude that the variable will be unassigned when 
the body is executed. 


For any immediate subexpression y of an expression x, where x is not a lambda 
expression, vis [unJassigned before y iff one of the following is true: 


y is the leftmost immediate subexpression of x and vis [un]Jassigned before x. 


y is the right-hand operand of a binary operator and v is [unJassigned after the 
left-hand operand. 


x iS an array access, y is the subexpression within the brackets, and v is 
[un]assigned after the subexpression before the brackets. 


x 1S a primary method invocation expression, y is the first argument expression 
in the method invocation expression, and v is [un]Jassigned after the primary 
expression that computes the target object. 


x is a method invocation expression or a class instance creation expression; y is 
an argument expression, but not the first; and vis [un]assigned after the argument 
expression to the left of y. 


x is a qualified class instance creation expression, y is the first argument 
expression in the class instance creation expression, and v is [un]assigned after 
the primary expression that computes the qualifying object. 


x iS an array creation expression; y is a dimension expression, but not the first; 
and vis [unassigned after the dimension expression to the left of y. 


x iS an array creation expression initialized via an array initializer; y is the array 
initializer in x; and vis [un]assigned after the dimension expression to the left 
of y. 
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16.2 Definite Assignment and Statements 


16.2.1 Empty Statements 


¢ vis [unJassigned after an empty statement (§14.6) iff it is [unJassigned before 
the empty statement. 


16.2.2. Blocks 


e A blank final member field v is definitely assigned (and moreover is not 
definitely unassigned) before the block ($14.2) that is the body of any method in 
the scope of vand before the declaration of any class declared within the scope 
of v. 


¢ A local variable v is definitely unassigned (and moreover is not definitely 
assigned) before the block that is the body of the constructor, method, instance 
initializer or static initializer that declares v. 


¢ Let c be a class declared within the scope of v. Then v is definitely assigned 
before the block that is the body of any constructor, method, instance initializer, 
or static initializer declared in ciff vis definitely assigned before the declaration 
of c. 


Note that there are no rules that would allow us to conclude that vis definitely unassigned 
before the block that is the body of any constructor, method, instance initializer, or static 
initializer declared in c. We can informally conclude that vis not definitely unassigned 
before the block that is the body of any constructor, method, instance initializer, or static 
initializer declared in c, but there is no need for such a rule to be stated explicitly. 


e vis [unassigned after an empty block iff v is [unJassigned before the empty 
block. 


¢ vis [un]assigned after a non-empty block iff v is [unJassigned after the last 
statement in the block. 


¢ vis [unJassigned before the first statement of the block iff v is [un]assigned 
before the block. 


¢ vis [un]assigned before any other statement s of the block iff vis [un]assigned 
after the statement immediately preceding s in the block. 


We say that vis definitely unassigned everywhere in a block B iff: 


¢ vis definitely unassigned before B. 
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¢ vis definitely assigned after e in every assignment expression Vv = e, V += e, V 
=e,V*=e, V/=e, V%=e, V<<=e, V>>= e, V>>>= e, Vé=e, V|=e, Or V*= 
e that occurs in B. 


¢ vis definitely assigned before every expression ++V, --v, v++, or v-- that occurs 
in B. 


These conditions are counterintuitive and require some explanation. Consider a simple 
assignment V = e. If vis definitely assigned after e, then either: 


¢ The assignment occurs in dead code, and Vv is vacuously definitely assigned. In this 
case, the assignment will not actually take place, and we can assume that vis not being 
assigned by the assignment expression. Or: 


* v was already assigned by an earlier expression prior to e. In this case the current 
assignment will cause a compile-time error. 


So, we can conclude that if the conditions are met by a program that causes no compile 
time error, then any assignments to Vin B will not actually take place at run time. 


16.2.3 Local Class Declaration Statements 


¢ vis [unJassigned after a local class declaration statement ($14.3) iff v is 
[unassigned before the local class declaration statement. 


16.2.4 Local Variable Declaration Statements 


¢ vis [unJassigned after a local variable declaration statement ($14.4) that contains 
no variable initializers iff vis [un]Jassigned before the local variable declaration 
statement. 


¢ vis definitely assigned after a local variable declaration statement that contains 
at least one variable initializer iff either v is definitely assigned after the last 
variable initializer in the local variable declaration statement or the last variable 
initializer in the declaration is in the declarator that declares v. 


e v is definitely unassigned after a local variable declaration statement that 
contains at least one variable initializer iff vis definitely unassigned after the last 
variable initializer in the local variable declaration statement and the last variable 
initializer in the declaration is not in the declarator that declares v. 


¢ vis [unJassigned before the first variable initializer in a local variable declaration 
statement iff vis [un]assigned before the local variable declaration statement. 


¢ vis definitely assigned before any variable initializer e other than the first one 
in the local variable declaration statement iff either vis definitely assigned after 
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the variable initializer to the left of e or the initializer expression to the left of e 
is in the declarator that declares v. 


vis definitely unassigned before any variable initializer e other than the first one 
in the local variable declaration statement iff vis definitely unassigned after the 
variable initializer to the left of e and the initializer expression to the left of e is 
not in the declarator that declares v. 


16.2.5 Labeled Statements 


¢ vis [unJassigned after a labeled statement z : s (where 1 is a label) ($14.7) iff v 
is [unJassigned after s and vis [un]assigned before every break statement that 
may exit the labeled statement z : s. 


¢ vis [unJassigned before s iff vis [unJassigned before x : s. 


16.2.6 Expression Statements 


¢ vis [un]assigned after an expression statement e; ($14.8) iff it is [unJassigned 
after e. 


¢ vis [unJassigned before e iff it is [unJassigned before e;. 


16.2.7 it Statements 


The following rules apply toa statement if (e) s(§14.9.1): 


¢ vis [unjassigned after it (e) siff vis [unJassigned after s and vis [un]assigned 
after e when false. 


¢ vis [unJassigned before e iff vis [unJassigned before if (e) s. 
¢ vis [unJassigned before s iff vis [unJassigned after e when true. 
The following rules apply toa statement if (e) S else T(§14.9.2): 


e vis [unJassigned after if (e) Ss else Tiff vis [unJassigned after s and vis 
[un]assigned after rT. 


¢ vis [unJassigned before e iff vis [unJassigned before if (e) S else T. 
¢ vis [unJassigned before s iff vis [unJassigned after e when true. 


¢ vis [unJassigned before riff vis [unJassigned after e when false. 
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16.2.8 assert Statements 


The following rules apply both to a statement assert e, and toa statement assert 
67. 2-63 ($14.10): 


¢ vis [un]assigned before e, iff vis [un]Jassigned before the assert statement. 


e vis definitely assigned after the assert statement iff v is definitely assigned 
before the assert statement. 


¢ vis definitely unassigned after the assert statement iff vis definitely unassigned 
before the assert statement and vis definitely unassigned after e; when true. 


The following rule applies to a statement assert e; : e2: 


¢ vis [unJassigned before e, iff vis [unJassigned after e, when false. 


16.2.9 switch Statements 


¢ vis [unJassigned after a switch statement (§14.11) iff all of the following are 
true: 


— Either there is a default label in the switch block or vis [unJassigned after 
the switch expression. 


— Either there are no switch labels in the switch block that do not begin a block- 
statement-group (that is, there are no switch labels immediately before the "}" 
that ends the switch block) or vis [un]assigned after the switch expression. 


— Either the switch block contains no block-statement-groups or v is 
[un]assigned after the last block-statement of the last block-statement-group. 


— vis [unJassigned before every break statement that may exit the switch 
statement. 


¢ vis [unJassigned before the switch expression iff vis [un]assigned before the 
switch Statement. 


If a switch block contains at least one block-statement-group, then the following 
rules also apply: 


¢ vis [un]assigned before the first block-statement of the first block-statement- 
group in the switch block iff vis [un]assigned after the switch expression. 


¢ vis [unJassigned before the first block-statement of any block-statement-group 
other than the first iff v is [unJassigned after the switch expression and v is 
[un]assigned after the preceding block-statement. 
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16.2.10 while Statements 


¢ vis [unJassigned after while (e) s(§14.12) iff vis [unJassigned after e when 
false and v is [un]assigned before every break statement for which the while 
statement is the break target. 


¢ vis definitely assigned before e iff vis definitely assigned before the while 
statement. 


¢ vis definitely unassigned before e iff all of the following are true: 
— vis definitely unassigned before the while statement. 
— Assuming vis definitely unassigned before e, vis definitely unassigned after s. 


— Assuming vis definitely unassigned before e, vis definitely unassigned before 
every cont inue statement for which the while statement is the continue target. 


¢ vis [unJassigned before s iff vis [unJassigned after e when true. 


16.2.11 do Statements 


¢ vis [unjassigned after do s while (e); ($14.13) iff vis [unJassigned after e 
when false and vis [un]assigned before every break statement for which the do 
statement is the break target. 


¢ v is definitely assigned before s iff v is definitely assigned before the do 
statement. 


¢ vis definitely unassigned before s iff all of the following are true: 
— vis definitely unassigned before the do statement. 


— Assuming vis definitely unassigned before s, vis definitely unassigned after 
e when true. 


¢ vis [unJassigned before e iff vis [unJassigned after s and vis [un]assigned before 
every continue statement for which the do statement is the continue target. 


16.2.12 for Statements 


The rules herein cover the basic for statement (§14.14.1). Since the enhanced for 
statement (§14.14.2) is defined by translation to a basic for statement, no special 
rules need to be provided for it. 


¢ vis [unJassigned after a for statement iff both of the following are true: 
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— Either a condition expression is not present or v is [un]assigned after the 
condition expression when false. 


— vis [un]Jassigned before every break statement for which the for statement 
is the break target. 


¢ vis [unJassigned before the initialization part of the for statement iff v is 
[unassigned before the for statement. 


¢ vis definitely assigned before the condition part of the for statement iff v is 
definitely assigned after the initialization part of the for statement. 


¢ vis definitely unassigned before the condition part of the for statement iff both 
of the following are true: 


— vis definitely unassigned after the initialization part of the for statement. 


— Assuming v is definitely unassigned before the condition part of the for 
statement, v is definitely unassigned after the incrementation part of the for 
statement. 


¢ vis [unJassigned before the contained statement iff either of the following is true: 


— A condition expression is present and v is [un]Jassigned after the condition 
expression when true. 


— No condition expression is present and vis [unassigned before the condition 
part of the for statement. 


¢ vis [un]assigned before the incrementation part of the for statement iff v is 
[unassigned after the contained statement and v is [unJassigned before every 
continue statement for which the for statement is the continue target. 


16.2.12.1 Initialization Part of for Statement 


¢ If the initialization part of the for statement is a local variable declaration 
statement, the rules of §16.2.4 apply. 


¢ Otherwise, if the initialization part is empty, then v is [un]assigned after the 
initialization part iff vis [unassigned before the initialization part. 


¢ Otherwise, three rules apply: 


— vis [unJassigned after the initialization part iff vis [unJassigned after the last 
expression statement in the initialization part. 


— vis [un]assigned before the first expression statement in the initialization part 
iff vis [unJassigned before the initialization part. 
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— vis [unJassigned before an expression statement s other than the first in 
the initialization part iff v is [unassigned after the expression statement 
immediately preceding s. 


16.2.12.2 Incrementation Part of for Statement 


¢ If the incrementation part of the for statement is empty, then vis [un]assigned 
after the incrementation part iff vis [un]assigned before the incrementation part. 


¢ Otherwise, three rules apply: 


— vis [un]assigned after the incrementation part iff v is [unJassigned after the 
last expression statement in the incrementation part. 


— vis [un]assigned before the first expression statement in the incrementation 
part iff vis [unJassigned before the incrementation part. 


— vis [unJassigned before an expression statement s other than the first in 
the incrementation part iff vis [unJassigned after the expression statement 
immediately preceding s. 


16.2.13 break, continue, return, and throw Statements 


¢ By convention, we say that vis [unJassigned after any break, continue, return, 
or throw statement (§14.15, §14.16, $14.17, $14.18). 


The notion that a variable is "[unJassigned after" a statement or expression really 
means "is [unassigned after the statement or expression completes normally". Because a 
break, continue, return, or throw statement never completes normally, it vacuously 
satisfies this notion. 


¢ In a return statement with an expression e or a throw statement with an 
expression e, vis [un]Jassigned before e iff vis [unJassigned before the return 
or throw statement. 


16.2.14 synchronized Statements 


¢ vis [unJassigned after synchronized (e) s(§14.19) iff vis [unJassigned after s. 


¢« v is [un]assigned before e iff v is [unJassigned before the statement 


synchronized (e) S. 


¢ vis [unJassigned before s iff vis [unJassigned after e. 
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16.2.15 try Statements 


These rules apply to every try statement ($14.20), whether or not it has a finally 
block: 


¢ vis [un]Jassigned before the try block iff v is [unJassigned before the try 
statement. 


¢ vis definitely assigned before a catch block iff vis definitely assigned before 
the try block. 


¢ vis definitely unassigned before a catch block iff all of the following are true: 
— vis definitely unassigned after the try block. 


— vis definitely unassigned before every return statement that belongs to the 
try block. 


— vis definitely unassigned after e in every statement of the form throw e that 
belongs to the try block. 


— vis definitely unassigned after every assert statement that occurs in the try 
block. 


— vis definitely unassigned before every break statement that belongs to the try 
block and whose break target contains (or is) the try statement. 


— vis definitely unassigned before every cont inue statement that belongs to the 
try block and whose continue target contains the try statement. 


If a try statement does not have a finally block, then this rule also applies: 


¢ vis [unJassigned after the try statement iff vis [unJassigned after the try block 
and vis [un]Jassigned after every catch block in the try statement. 


If a try statement does have a finally block, then these rules also apply: 


¢ vis definitely assigned after the try statement iff at least one of the following 
is true: 


— vis definitely assigned after the try block and vis definitely assigned after 
every catch block in the try statement. 


— vis definitely assigned after the finally block. 


¢ vis definitely unassigned after the try statement iff vis definitely unassigned 
after the finally block. 


¢ vis definitely assigned before the finally block iff vis definitely assigned 
before the try statement. 
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¢ vis definitely unassigned before the finally block iff all of the following are 
true: 


— vis definitely unassigned after the try block. 


— vis definitely unassigned before every return statement that belongs to the 
try block. 


— vis definitely unassigned after e in every statement of the form throw e that 
belongs to the try block. 


— vis definitely unassigned after every assert statement that occurs in the try 
block. 


— vis definitely unassigned before every break statement that belongs to the try 
block and whose break target contains (or is) the try statement. 


— vis definitely unassigned before every continue statement that belongs to the 
try block and whose continue target contains the try statement. 


— vis definitely unassigned after every catch block of the try statement. 


16.3 Definite Assignment and Parameters 


¢ A formal parameter v of a method or constructor (§8.4.1, §8.8.1) is definitely 
assigned (and moreover is not definitely unassigned) before the body of the 
method or constructor. 


e An exception parameter v of a catch clause ($14.20) is definitely assigned (and 
moreover is not definitely unassigned) before the body of the catch clause. 


16.4 Definite Assignment and Array Initializers 


¢ vis [unJassigned after an empty array initializer ($10.6) iff vis [unJassigned 
before the empty array initializer. 


¢ vis [unassigned after a non-empty array initializer iff vis [unassigned after the 
last variable initializer in the array initializer. 


¢ vis [un]assigned before the first variable initializer of the array initializer iff v 
is [unJassigned before the array initializer. 
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¢ vis [unJassigned before any other variable initializer e of the array initializer iff v 
is [unJassigned after the variable initializer to the left of e in the array initializer. 


16.5 Definite Assignment and Enum Constants 


The rules determining when a variable is definitely assigned or definitely 
unassigned before an enum constant (§8.9.1) are given in $16.8. 


This is because an enum constant is essentially a static final field (§8.3.1.1, §8.3.1.2) 
that is initialized with a class instance creation expression (§15.9). 


¢ vis definitely assigned before the declaration of a class body of an enum constant 
with no arguments that is declared within the scope of viff vis definitely assigned 
before the enum constant. 


¢ vis definitely assigned before the declaration of a class body of an enum constant 
with arguments that is declared within the scope of viff vis definitely assigned 
after the last argument expression of the enum constant 


The definite assignment/unassignment status of any construct within the class body 
of an enum constant is governed by the usual rules for classes. 


¢ v is [unJassigned before the first argument to an enum constant iff it is 
[un]assigned before the enum constant. 


¢ vis [un]assigned before y (an argument of an enum constant, but not the first) 
iff vis [unJassigned after the argument to the left of y. 


16.6 Definite Assignment and Anonymous Classes 


¢ vis definitely assigned before an anonymous class declaration (§15.9.5) that is 
declared within the scope of viff vis definitely assigned after the class instance 
creation expression that declares the anonymous class. 


It should be clear that if an anonymous class is implicitly defined by an enum constant, the 
tules of §16.5 apply. 
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16.7 Definite Assignment and Member Types 


Let c be a class, and let vbe a blank final member field of c. Then: 


¢ vis definitely assigned (and moreover, not definitely unassigned) before the 
declaration of any member type (§8.5, $9.5) of c. 


Let c be a class declared within the scope of v. Then: 


¢ vis definitely assigned before a member type declaration of c iff vis definitely 
assigned before the declaration of c. 


16.8 Definite Assignment and Static Initializers 


Let c be a class declared within the scope of v. Then: 


¢ vis definitely assigned before an enum constant (§8.9.1) or static variable 
initializer (§8.3.2) of ciff vis definitely assigned before the declaration of c. 


Note that there are no rules that would allow us to conclude that vis definitely unassigned 
before a static variable initializer or enum constant. We can informally conclude that v 
is not definitely unassigned before any static variable initializer of c, but there is no need 
for such a rule to be stated explicitly. 


Let c be a class, and let v be a blank static final member field of c, declared 
in c. Then: 


¢ vis definitely unassigned (and moreover is not definitely assigned) before the 
leftmost enum constant, static initializer ($8.7), or static variable initializer of c. 


¢ vis [unJassigned before an enum constant, static initializer, or static variable 
initializer of c other than the leftmost iff v is [unJassigned after the preceding 
enum constant, static initializer, or static variable initializer of c. 


Let c be a class, and let v be a blank static final member field of c, declared 
in a superclass of c. Then: 


¢ vis definitely assigned (and moreover is not definitely unassigned) before every 
enum constant of c. 


¢ vis definitely assigned (and moreover is not definitely unassigned) before the 
block that is the body of a static initializer of c. 


¢ vis definitely assigned (and moreover is not definitely unassigned) before every 
static variable initializer of c. 
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16.9 Definite Assignment, Constructors, and Instance 
Initializers 


Let c be a class declared within the scope of v. Then: 


¢ vis definitely assigned before an instance variable initializer (§8.3.2) of c iff v 
is definitely assigned before the declaration of c. 


Note that there are no rules that would allow us to conclude that vis definitely unassigned 
before an instance variable initializer. We can informally conclude that vis not definitely 
unassigned before any instance variable initializer of c, but there is no need for such a 
tule to be stated explicitly. 
Let cbea class, and let vbe a blank final non-static member field of c, declared 
in c. Then: 


¢ vis definitely unassigned (and moreover is not definitely assigned) before the 
leftmost instance initializer ($8.6) or instance variable initializer of c. 


¢ vis [un]assigned before an instance initializer or instance variable initializer of c 
other than the leftmost iff vis [un]assigned after the preceding instance initializer 
or instance variable initializer of c. 


The following rules hold within the constructors (§8.8.7) of class c: 


¢ vis definitely assigned (and moreover is not definitely unassigned) after an 
alternate constructor invocation (§8.8.7.1). 


¢ vis definitely unassigned (and moreover is not definitely assigned) before an 
explicit or implicit superclass constructor invocation (§8.8.7.1). 


¢ If c has no instance initializers or instance variable initializers, then v is not 
definitely assigned (and moreover is definitely unassigned) after an explicit or 
implicit superclass constructor invocation. 


¢ If chas at least one instance initializer or instance variable initializer then vis 
[un]assigned after an explicit or implicit superclass constructor invocation iff vis 
[un]assigned after the rightmost instance initializer or instance variable initializer 
of c. 


Let c be a class, and let v be a blank final member field of c, declared in a 
superclass of c. Then: 


¢ vis definitely assigned (and moreover is not definitely unassigned) before the 
block that is the body of a constructor or instance initializer of c. 
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¢ vis definitely assigned (and moreover is not definitely unassigned) before every 
instance variable initializer of c. 
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CHAPTER 17 


Threads and Locks 


Wine most of the discussion in the preceding chapters is concerned only with 
the behavior of code as executed a single statement or expression at a time, that is, 
by a single thread, the Java Virtual Machine can support many threads of execution 
at once. These threads independently execute code that operates on values and 
objects residing in a shared main memory. Threads may be supported by having 
many hardware processors, by time-slicing a single hardware processor, or by time- 
slicing many hardware processors. 


Threads are represented by the Thread class. The only way for a user to create 
a thread is to create an object of this class; each thread is associated with such 
an object. A thread will start when the start () method is invoked on the 
corresponding Thread object. 


The behavior of threads, particularly when not correctly synchronized, can 
be confusing and counterintuitive. This chapter describes the semantics of 
multithreaded programs; it includes rules for which values may be seen by a read of 
shared memory that is updated by multiple threads. As the specification is similar to 
the memory models for different hardware architectures, these semantics are known 
as the Java programming language memory model. When no confusion can arise, 
we will simply refer to these rules as "the memory model". 


These semantics do not prescribe how a multithreaded program should be executed. 
Rather, they describe the behaviors that multithreaded programs are allowed 
to exhibit. Any execution strategy that generates only allowed behaviors is an 
acceptable execution strategy. 
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17.1 Synchronization 


The Java programming language provides multiple mechanisms for 
communicating between threads. The most basic of these methods is 
synchronization, which is implemented using monitors. Each object in Java is 
associated with a monitor, which a thread can lock or unlock. Only one thread at 
a time may hold a lock on a monitor. Any other threads attempting to lock that 
monitor are blocked until they can obtain a lock on that monitor. A thread t may 
lock a particular monitor multiple times; each unlock reverses the effect of one 
lock operation. 


The synchronized statement (§14.19) computes a reference to an object; it then 
attempts to perform a lock action on that object's monitor and does not proceed 
further until the lock action has successfully completed. After the lock action has 
been performed, the body of the synchronized statement is executed. If execution 
of the body is ever completed, either normally or abruptly, an unlock action is 
automatically performed on that same monitor. 


A synchronized method (§8.4.3.6) automatically performs a lock action when it is 
invoked; its body is not executed until the lock action has successfully completed. If 
the method is an instance method, it locks the monitor associated with the instance 
for which it was invoked (that is, the object that will be known as this during 
execution of the body of the method). If the method is static, it locks the monitor 
associated with the class object that represents the class in which the method is 
defined. If execution of the method's body is ever completed, either normally or 
abruptly, an unlock action is automatically performed on that same monitor. 


The Java programming language neither prevents nor requires detection of 
deadlock conditions. Programs where threads hold (directly or indirectly) locks 
on multiple objects should use conventional techniques for deadlock avoidance, 
creating higher-level locking primitives that do not deadlock, if necessary. 


Other mechanisms, such as reads and writes of volatile variables and the use 
of classes in the java.util.concurrent package, provide alternative ways of 
synchronization. 


17.2. Wait Sets and Notification 


Every object, in addition to having an associated monitor, has an associated wait 
set. A wait set is a set of threads. 
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When an object is first created, its wait set is empty. Elementary actions that 
add threads to and remove threads from wait sets are atomic. Wait sets are 
manipulated solely through the methods object.wait, Object.notify, and 
Object .notifyAll. 


Wait set manipulations can also be affected by the interruption status of a thread, 
and by the Thread class's methods dealing with interruption. Additionally, the 
Thread class's methods for sleeping and joining other threads have properties 
derived from those of wait and notification actions. 


17.2.1 Wait 


Wait actions occur upon invocation of wait (), or the timed forms wait (long 


millisecs) and wait (long millisecs, int nanosecs). 


A call of wait (long millisecs) with a parameter of zero, or a call of wait (long 
millisecs, int nanosecs) with two zero parameters, is equivalent to an invocation 
of wait (). 


A thread returns normally from a wait if it returns without throwing an 


InterruptedException. 


Let thread ¢ be the thread executing the wait method on object m, and let n be the 
number of lock actions by ¢ on m that have not been matched by unlock actions. 
One of the following actions occurs: 


¢ If nis zero (i.e., thread ¢ does not already possess the lock for target m), then an 
IllegalMonitorStateException is thrown. 


¢ If this is a timed wait and the nanosecs argument is not in the range of 0-999999 
or the millisecs argument is negative, then an IllegalArgumentException is 
thrown. 


¢ If thread ¢ is interrupted, then an InterruptedException is thrown and 1's 
interruption status is set to false. 


¢ Otherwise, the following sequence occurs: 


1. Thread f is added to the wait set of object m, and performs 7 unlock actions 
on m. 


2. Thread t does not execute any further instructions until it has been removed 
from m's wait set. The thread may be removed from the wait set due to any 
one of the following actions, and will resume sometime afterward: 
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— A notify action being performed on m in which t is selected for removal 
from the wait set. 


— A notifyAll action being performed on m. 
— An interrupt action being performed on t. 


— If this is a timed wait, an internal action removing ¢ from m's wait set that 
occurs after at least millisecs milliseconds plus nanosecs nanoseconds 
elapse since the beginning of this wait action. 


— An internal action by the implementation. Implementations are permitted, 
although not encouraged, to perform "spurious wake-ups", that is, to 
remove threads from wait sets and thus enable resumption without explicit 
instructions to do so. 


Notice that this provision necessitates the Java coding practice of using wait 

only within loops that terminate only when some logical condition that the thread 

is waiting for holds. 
Each thread must determine an order over the events that could cause it to 
be removed from a wait set. That order does not have to be consistent with 
other orderings, but the thread must behave as though those events occurred 
in that order. 


For example, if a thread ¢ is in the wait set for m, and then both an interrupt 
of ¢t and a notification of m occur, there must be an order over these events. 
If the interrupt is deemed to have occurred first, then ¢ will eventually return 
from wait by throwing InterruptedException, and some other thread in 
the wait set for m (if any exist at the time of the notification) must receive 
the notification. If the notification is deemed to have occurred first, then f 
will eventually return normally from wait with an interrupt still pending. 


3. Thread t performs n lock actions on m. 


4. If thread t was removed from m's wait set in step 2 due to an interrupt, 
then f's interruption status is set to false and the wait method throws 


InterruptedException. 


17.2.2 Notification 
Notification actions occur upon invocation of methods notify and notifyAll. 


Let thread ¢ be the thread executing either of these methods on object m, and let 
n be the number of lock actions by ¢ on m that have not been matched by unlock 
actions. One of the following actions occurs: 
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¢ If nis zero, then an IllegalMonitorStateException Is thrown. 


This is the case where thread ¢ does not already possess the lock for target m. 


¢ If n is greater than zero and this is a notify action, then if m's wait set is not 
empty, a thread u that is a member of m's current wait set is selected and removed 
from the wait set. 


There is no guarantee about which thread in the wait set is selected. This removal 
from the wait set enables u's resumption in a wait action. Notice, however, that 
u's lock actions upon resumption cannot succeed until some time after ¢ fully 
unlocks the monitor for m. 


¢ If n is greater than zero and this is a notifyAll action, then all threads are 
removed from m's wait set, and thus resume. 


Notice, however, that only one of them at a time will lock the monitor required 
during the resumption of wait. 


17.2.3. Interruptions 


Interruption actions occur upon invocation of Thread.interrupt, as well as 
methods defined to invoke it in turn, such as ThreadGroup. interrupt. 


Let ¢ be the thread invoking u.interrupt, for some thread u, where t and u may 
be the same. This action causes u's interruption status to be set to true. 


Additionally, if there exists some object m whose wait set contains u, then u is 
removed from m's wait set. This enables u to resume in a wait action, in which case 
this wait will, after re-locking m's monitor, throw InterruptedException. 


Invocations of Thread.isInterrupted can determine a thread's interruption 
status. The static method Thread. interrupted may be invoked by a thread to 
observe and clear its own interruption status. 


17.2.4 Interactions of Waits, Notification, and Interruption 


The above specifications allow us to determine several properties having to do with 
the interaction of waits, notification, and interruption. 


If a thread is both notified and interrupted while waiting, it may either: 


* return normally from wait, while still having a pending interrupt (in other words, 
a call to Thread. interrupted would return true) 


¢ return from wait by throwing an InterruptedException 
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The thread may not reset its interrupt status and return normally from the call to 


wait. 


Similarly, notifications cannot be lost due to interrupts. Assume that a set s of 
threads is in the wait set of an object m, and another thread performs a notify on 
m. Then either: 


¢ at least one thread in s must return normally from wait, or 


¢ all of the threads in s must exit wait by throwing InterruptedException. 


Note that if a thread is both interrupted and woken via notify, and that thread 
returns from wait by throwing an InterruptedException, then some other thread 
in the wait set must be notified. 


17.3 Sleep and Yield 


Thread.sleep causes the currently executing thread to sleep (temporarily cease 
execution) for the specified duration, subject to the precision and accuracy of 
system timers and schedulers. The thread does not lose ownership of any monitors, 
and resumption of execution will depend on scheduling and the availability of 
processors on which to execute the thread. 


It is important to note that neither Thread.sleep nor Thread. yield have any 
synchronization semantics. In particular, the compiler does not have to flush 
writes cached in registers out to shared memory before a call to Thread.sleep 
or Thread. yield, nor does the compiler have to reload values cached in registers 
after a call to Thread. sleep Or Thread. yield. 


For example, in the following (broken) code fragment, assume that this.done is a non- 
volatile boolean field: 


while (!this.done) 
Thread.sleep (1000) ; 


The compiler is free to read the field this .done just once, and reuse the cached value in 
each execution of the loop. This would mean that the loop would never terminate, even if 
another thread changed the value of this.done. 
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17.4 Memory Model 


A memory model describes, given a program and an execution trace of that 
program, whether the execution trace is a legal execution of the program. The 
Java programming language memory model works by examining each read in an 
execution trace and checking that the write observed by that read is valid according 
to certain rules. 


The memory model describes possible behaviors of a program. An implementation 
is free to produce any code it likes, as long as all resulting executions of a program 
produce a result that can be predicted by the memory model. 


This provides a great deal of freedom for the implementor to perform a myriad of 
code transformations, including the reordering of actions and removal of unnecessary 
synchronization. 


Example 17.4-1. Incorrectly Synchronized Programs May Exhibit Surprising Behavior 


The semantics of the Java programming language allow compilers and microprocessors to 
perform optimizations that can interact with incorrectly synchronized code in ways that 
can produce behaviors that seem paradoxical. Here are some examples of how incorrectly 
synchronized programs may exhibit surprising behaviors. 


Consider, for example, the example program traces shown in Table 17.4-A. This program 
uses local variables r1 and r2 and shared variables A and B. Initially, A == B == 0. 


Table 17.4-A. Surprising results caused by statement reordering - original code 


Thread 1 Thread 2 

1:r2 = A; 3:r1 = B; 

2:B = 1; 4:A = 2; 

It may appear that the result r2. == 2 and rl == 1 is impossible. Intuitively, either 


instruction | or instruction 3 should come first in an execution. If instruction 1 comes first, 
it should not be able to see the write at instruction 4. If instruction 3 comes first, it should 
not be able to see the write at instruction 2. 


If some execution exhibited this behavior, then we would know that instruction 4 came 
before instruction 1, which came before instruction 2, which came before instruction 3, 
which came before instruction 4. This is, on the face of it, absurd. 


However, compilers are allowed to reorder the instructions in either thread, when this 
does not affect the execution of that thread in isolation. If instruction 1 is reordered with 
instruction 2, as shown in the trace in Table 17.4-B, then it is easy to see how the result 
r2 == 2andrl1 == 1 might occur. 
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Table 17.4-B. Surprising results caused by statement reordering - valid compiler 
transformation 


Thread 1 Thread 2 
B= 1; rl = B; 
Ee Ks A.= 2; 


To some programmers, this behavior may seem "broken". However, it should be noted that 
this code is improperly synchronized: 


¢ there is a write in one thread, 
* aread of the same variable by another thread, 
¢ and the write and read are not ordered by synchronization. 


This situation is an example of a data race (§17.4.5). When code contains a data race, 
counterintuitive results are often possible. 


Several mechanisms can produce the reordering in Table 17.4-B. A Just-In-Time compiler 
ina Java Virtual Machine implementation may rearrange code, or the processor. In addition, 
the memory hierarchy of the architecture on which a Java Virtual Machine implementation 
is run may make it appear as if code is being reordered. In this chapter, we shall refer to 
anything that can reorder code as a compiler. 


Another example of surprising results can be seen in Table 17.4-C. Initially, p == q and 
p.x == 0. This program is also incorrectly synchronized; it writes to shared memory 
without enforcing any ordering between those writes. 


Table 17.4-C. Surprising results caused by forward substitution 


Thread 1 Thread 2 
rl = p; r6 = p; 
C2 =< PLexG r6.x = 3; 
r3 = qG 

r4 = r3.x; 

r5 = rl.x; 


One common compiler optimization involves having the value read for r2 reused for r5: 
they are both reads of r1 . x with no intervening write. This situation is shown in Table 17.4- 
D. 
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Table 17.4-D. Surprising results caused by forward substitution 


Thread 1 Thread 2 
rl =p; r6 = p; 
r2 = rl.x; r6.x = 3; 
r3 = Qi 

r4 = r3.x; 

rors e2 


Now consider the case where the assignment to r6.x in Thread 2 happens between the 
first read of r1.x and the read of r3.x in Thread 1. If the compiler decides to reuse the 
value of r2 for the r5, then r2 and r5 will have the value 0, and r4 will have the value 
3. From the perspective of the programmer, the value stored at p.x has changed from 0 
to 3 and then changed back. 


The memory model determines what values can be read at every point in the 
program. The actions of each thread in isolation must behave as governed by the 
semantics of that thread, with the exception that the values seen by each read are 
determined by the memory model. When we refer to this, we say that the program 
obeys intra-thread semantics. Intra-thread semantics are the semantics for single- 
threaded programs, and allow the complete prediction of the behavior of a thread 
based on the values seen by read actions within the thread. To determine if the 
actions of thread ¢ in an execution are legal, we simply evaluate the implementation 
of thread ¢ as it would be performed in a single-threaded context, as defined in the 
rest of this specification. 


Each time the evaluation of thread f generates an inter-thread action, it must match 
the inter-thread action a of t that comes next in program order. If a is a read, then 
further evaluation of t uses the value seen by a as determined by the memory model. 


This section provides the specification of the Java programming language memory 
model except for issues dealing with final fields, which are described in §17.5. 


The memory model specified herein is not fundamentally based in the object-oriented 
nature of the Java programming language. For conciseness and simplicity in our 
examples, we often exhibit code fragments without class or method definitions, or explicit 
dereferencing. Most examples consist of two or more threads containing statements with 
access to local variables, shared global variables, or instance fields of an object. We 
typically use variables names such as r1 or r2 to indicate variables local to a method or 
thread. Such variables are not accessible by other threads. 
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17.4.1 Shared Variables 


Memory that can be shared between threads is called shared memory or heap 
memory. 


All instance fields, static fields, and array elements are stored in heap memory. 
In this chapter, we use the term variable to refer to both fields and array elements. 


Local variables (§ 14.4), formal method parameters (§8.4.1), and exception handler 
parameters (§14.20) are never shared between threads and are unaffected by the 
memory model. 


Two accesses to (reads of or writes to) the same variable are said to be conflicting 
if at least one of the accesses is a write. 


17.4.2 Actions 


An inter-thread action is an action performed by one thread that can be detected or 
directly influenced by another thread. There are several kinds of inter-thread action 
that a program may perform: 


¢ Read (normal, or non-volatile). Reading a variable. 
¢ Write (normal, or non-volatile). Writing a variable. 
¢ Synchronization actions, which are: 
— Volatile read. A volatile read of a variable. 
— Volatile write. A volatile write of a variable. 
— Lock. Locking a monitor 
— Unlock. Unlocking a monitor. 
— The (synthetic) first and last action of a thread. 
— Actions that start a thread or detect that a thread has terminated (§17.4.4). 


¢ External Actions. An external action is an action that may be observable outside 
of an execution, and has a result based on an environment external to the 
execution. 


¢ Thread divergence actions ($17.4.9). A thread divergence action is only 
performed by a thread that is in an infinite loop in which no memory, 
synchronization, or external actions are performed. If a thread performs a thread 
divergence action, it will be followed by an infinite number of thread divergence 
actions. 
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Thread divergence actions are introduced to model how a thread may cause all other 
threads to stall and fail to make progress. 


This specification is only concerned with inter-thread actions. We do not need to 
concern ourselves with intra-thread actions (e.g., adding two local variables and 
storing the result in a third local variable). As previously mentioned, all threads 
need to obey the correct intra-thread semantics for Java programs. We will usually 
refer to inter-thread actions more succinctly as simply actions. 


An action a is described by a tuple < ¢, k, v, u >, comprising: 
¢ t¢- the thread performing the action 

¢ k - the kind of action 

e y- the variable or monitor involved in the action. 


For lock actions, v is the monitor being locked; for unlock actions, v is the 
monitor being unlocked. 


If the action is a (volatile or non-volatile) read, v is the variable being read. 
If the action is a (volatile or non-volatile) write, v is the variable being written. 
¢ u-an arbitrary unique identifier for the action 


An external action tuple contains an additional component, which contains the 
results of the external action as perceived by the thread performing the action. This 
may be information as to the success or failure of the action, and any values read 
by the action. 


Parameters to the external action (e.g., which bytes are written to which socket) are 
not part of the external action tuple. These parameters are set up by other actions 
within the thread and can be determined by examining the intra-thread semantics. 
They are not explicitly discussed in the memory model. 


In non-terminating executions, not all external actions are observable. Non- 
terminating executions and observable actions are discussed in §17.4.9. 


17.4.3. Programs and Program Order 


Among all the inter-thread actions performed by each thread f, the program order 
of tis a total order that reflects the order in which these actions would be performed 
according to the intra-thread semantics of f. 
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A set of actions is sequentially consistent if all actions occur in a total order (the 
execution order) that is consistent with program order, and furthermore, each read 
r of a variable v sees the value written by the write w to v such that: 


¢ wcomes before r in the execution order, and 


e there is no other write w' such that w comes before w' and w' comes before r in 
the execution order. 


Sequential consistency is a very strong guarantee that is made about visibility and 
ordering in an execution of a program. Within a sequentially consistent execution, 
there is a total order over all individual actions (such as reads and writes) which is 
consistent with the order of the program, and each individual action is atomic and 
is immediately visible to every thread. 


If a program has no data races, then all executions of the program will appear to 
be sequentially consistent. 


Sequential consistency and/or freedom from data races still allows errors arising 
from groups of operations that need to be perceived atomically and are not. 


If we were to use sequential consistency as our memory model, many of the compiler and 
processor optimizations that we have discussed would be illegal. For example, in the trace 
in Table 17.4-C, as soon as the write of 3 to p. x occurred, subsequent reads of that location 
would be required to see that value. 


17.4.4 Synchronization Order 


Every execution has a synchronization order. A synchronization order is a total 
order over all of the synchronization actions of an execution. For each thread f, 
the synchronization order of the synchronization actions (§17.4.2) in ¢ is consistent 
with the program order (§17.4.3) of f. 


Synchronization actions induce the synchronized-with relation on actions, defined 
as follows: 


¢ Anunlock action on monitor m synchronizes-with all subsequent lock actions on 
m (where "subsequent" is defined according to the synchronization order). 


¢« A write to a volatile variable v (§8.3.1.4) synchronizes-with all subsequent 
reads of v by any thread (where "subsequent" is defined according to the 
synchronization order). 


e An action that starts a thread synchronizes-with the first action in the thread it 
starts. 
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¢ The write of the default value (zero, false, or null) to each variable 
synchronizes-with the first action in every thread. 


Although it may seem a little strange to write a default value to a variable before the 
object containing the variable is allocated, conceptually every object is created at the 
start of the program with its default initialized values. 
¢ The final action in a thread 171 synchronizes-with any action in another thread r2 
that detects that 71 has terminated. 


T2 may accomplish this by calling T1.isAlive() or T1.join(). 


¢ If thread rz interrupts thread r2, the interrupt by T1 synchronizes-with any point 
where any other thread (including 72) determines that r2 has been interrupted (by 
having an InterruptedExcept ion thrown or by invoking Thread. interrupted 
or Thread. isInterrupted). 


The source of a synchronizes-with edge is called a release, and the destination is 
called an acquire. 


17.4.5 Happens-before Order 

Two actions can be ordered by a happens-before relationship. If one action 
happens-before another, then the first is visible to and ordered before the second. 
If we have two actions x and y, we write hb(x, y) to indicate that x happens-before y. 


¢ If x and y are actions of the same thread and x comes before y in program order, 
then hb(x, y). 


e There is a happens-before edge from the end of a constructor of an object to the 
start of a finalizer ($12.6) for that object. 


¢ If an action x synchronizes-with a following action y, then we also have hb(x, y). 
¢ If hb(x, y) and hb(y, z), then hb(x, z). 


The wait methods of class object (§17.2.1) have lock and unlock actions 
associated with them; their happens-before relationships are defined by these 
associated actions. 


It should be noted that the presence of a happens-before relationship between 
two actions does not necessarily imply that they have to take place in that order 
in an implementation. If the reordering produces results consistent with a legal 
execution, it is not illegal. 
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For example, the write of a default value to every field of an object constructed by a thread 
need not happen before the beginning of that thread, as long as no read ever observes that 
fact. 


More specifically, if two actions share a happens-before relationship, they do not 
necessarily have to appear to have happened in that order to any code with which 
they do not share a happens-before relationship. Writes in one thread that are in 
a data race with reads in another thread may, for example, appear to occur out of 
order to those reads. 


The happens-before relation defines when data races take place. 


A set of synchronization edges, S, is sufficient if it is the minimal set such that the 
transitive closure of S with the program order determines all of the happens-before 
edges in the execution. This set is unique. 


It follows from the above definitions that: 
¢ An unlock on a monitor happens-before every subsequent lock on that monitor. 


¢ A write to a volatile field (§8.3.1.4) happens-before every subsequent read of 
that field. 


¢ Acall to start () ona thread happens-before any actions in the started thread. 


e All actions in a thread happen-before any other thread successfully returns from 
a join() on that thread. 


¢ The default initialization of any object happens-before any other actions (other 
than default-writes) of a program. 


When a program contains two conflicting accesses (§17.4.1) that are not ordered 
by a happens-before relationship, it is said to contain a data race. 


The semantics of operations other than inter-thread actions, such as reads of array 
lengths (§10.7), executions of checked casts (§5.5, §15.16), and invocations of 
virtual methods ($15.12), are not directly affected by data races. 


Therefore, a data race cannot cause incorrect behavior such as returning the wrong length 
for an array. 


A program is correctly synchronized if and only if all sequentially consistent 
executions are free of data races. 


If a program is correctly synchronized, then all executions of the program will 
appear to be sequentially consistent ($17.4.3). 
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This is an extremely strong guarantee for programmers. Programmers do not need to 
reason about reorderings to determine that their code contains data races. Therefore they 
do not need to reason about reorderings when determining whether their code is correctly 
synchronized. Once the determination that the code is correctly synchronized is made, the 
programmer does not need to worry that reorderings will affect his or her code. 


A program must be correctly synchronized to avoid the kinds of counterintuitive behaviors 
that can be observed when code is reordered. The use of correct synchronization does 
not ensure that the overall behavior of a program is correct. However, its use does allow 
a programmer to reason about the possible behaviors of a program in a simple way; 
the behavior of a correctly synchronized program is much less dependent on possible 
reorderings. Without correct synchronization, very strange, confusing and counterintuitive 
behaviors are possible. 


We say that a read r of a variable v is allowed to observe a write w to v if, in the 
happens-before partial order of the execution trace: 
¢ ris not ordered before w (i.e., it is not the case that hb(r, w)), and 


¢ there is no intervening write w' to v (i.e. no write w' to v such that hb(w, w') and 
hb(w', r)). 

Informally, a read r is allowed to see the result of a write w if there is no happens- 

before ordering to prevent that read. 


A set of actions A is happens-before consistent if for all reads r in A, where W(r) 
is the write action seen by /, it is not the case that either hb(r, W(r)) or that there 
exists a write w in A such that w.v = r.v and hb(W(r), w) and hb(y, r). 


In a happens-before consistent set of actions, each read sees a write that it is allowed 
to see by the happens-before ordering. 
Example 17.4.5-1. Happens-before Consistency 


For the trace in Table 17.4.5-A, initially A == B == 0. The trace can observe r2 == 
and r1 == 0 and still be happens-before consistent, since there are execution orders that 
allow each read to see the appropriate write. 


Table 17.4.5-A. Behavior allowed by happens-before consistency, but not sequential 


consistency. 

Thread 1 Thread 2 
B= 1; A = 2; 
r2 =A; rl = B; 


Since there is no synchronization, each read can see either the write of the initial value or 
the write by the other thread. An execution order that displays this behavior is: 
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1: B= 1; 
3: A = 2; 
2: r2 =A; // sees initial write of 0 
4: rl = B; // sees initial write of 0 


Another execution order that is happens-before consistent is: 


1: r2 =A; // sees write of A = 2 
3: rl = B; // sees write of B=1 
23° B=. Lh; 
4: A= 2; 


In this execution, the reads see writes that occur later in the execution order. This may seem 
counterintuitive, but is allowed by happens-before consistency. Allowing reads to see later 
writes can sometimes produce unacceptable behaviors. 


17.4.6 Executions 

An execution F is described by a tuple < P, A, po, so, W, V, sw, hb >, comprising: 
e P-aprogram 

e A -a set of actions 


* po - program order, which for each thread ¢, is a total order over all actions 
performed by tin A 


* so - synchronization order, which is a total order over all synchronization actions 
inA 
¢ W-awrite-seen function, which for each read rin A, gives W(r), the write action 


seen by rin E. 


¢ V-a value-written function, which for each write w in A, gives V(w), the value 
written by w in E. 


* sw - synchronizes-with, a partial order over synchronization actions 
¢ hb - happens-before, a partial order over actions 


Note that the synchronizes-with and happens-before elements are uniquely 
determined by the other components of an execution and the rules for well-formed 
executions (§17.4.7). 


An execution is happens-before consistent if its set of actions is happens-before 
consistent (§17.4.5). 
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17.4.7. Well-Formed Executions 


We only consider well-formed executions. An execution E = < P, A, po, so, W, V, 
sw, hb > is well formed if the following are true: 


1. 


Each read sees a write to the same variable in the execution. 


All reads and writes of volatile variables are volatile actions. For all reads r 
in A, we have W(r) in A and W(r).v = r.v. The variable r.v is volatile if and 
only if r is a volatile read, and the variable w.v is volatile if and only if w is 
a volatile write. 


The happens-before order is a partial order. 


The happens-before order is given by the transitive closure of synchronizes- 
with edges and program order. It must be a valid partial order: reflexive, 
transitive and antisymmetric. 


The execution obeys intra-thread consistency. 


For each thread f, the actions performed by ¢ in A are the same as would 
be generated by that thread in program-order in isolation, with each write w 
writing the value V(w), given that each read r sees the value V/W(r)). Values 
seen by each read are determined by the memory model. The program order 
given must reflect the program order in which the actions would be performed 
according to the intra-thread semantics of P. 


The execution is happens-before consistent (§17.4.6). 
The execution obeys synchronization-order consistency. 


For all volatile reads r in A, it is not the case that either so(r, W(r)) or that there 
exists a write w in A such that w.v = r.v and so(W(r), w) and so(w, r). 


17.4.8 Executions and Causality Requirements 


We use f|q to denote the function given by restricting the domain of f to d. For all x in d, 
flax) = f(x), and for all x not in d, flax) is undefined. 


We use p|, to represent the restriction of the partial order p to the elements in d. For all x,y in 
d, p(x,y) if and only if p|q(x,y). If either x or y are not in d, then it is not the case that p|q(x,y). 


A well-formed execution E = < P, A, po, so, W, V, sw, hb > is validated by 
committing actions from A. If all of the actions in A can be committed, then the 
execution satisfies the causality requirements of the Java programming language 
memory model. 
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Starting with the empty set as Co, we perform a sequence of steps where we take 
actions from the set of actions A and add them to a set of committed actions C; to 
get a new set of committed actions Cj;;. To demonstrate that this is reasonable, 
for each C; we need to demonstrate an execution EF containing C; that meets certain 
conditions. 


Formally, an execution EF’ satisfies the causality requirements of the Java 
programming language memory model if and only if there exist: 


¢ Sets of actions Co, C7, ... such that: 
— Co is the empty set 
— C;is a proper subset of Ci4) 
-A=U(Cp, Cj, ...) 
If A is finite, then the sequence Co, C), ... will be finite, ending in a set C,, =A. 


If A is infinite, then the sequence Co, C;, ... may be infinite, and it must be the 
case that the union of all elements of this infinite sequence is equal to A. 


¢ Well-formed executions F7, ..., where E; = < P, Aj, po;, so, Wi, Vi, sw; hb; >. 


Given these sets of actions Co, ... and executions EF), ... , every action in C; must 
be one of the actions in £;. All actions in C; must share the same relative happens- 
before order and synchronization order in both E; and E. Formally: 


1. C;is a subset of A; 
2. hbilc, = hdc, 
3. soilc, = solc, 


The values written by the writes in C; must be the same in both £; and E. Only the 
reads in C;.; need to see the same writes in E; as in E. Formally: 


4. Vilc,= Vic, 
5. Wilc;., = We. 


All reads in £; that are not in C;.; must see writes that happen-before them. Each 
read r in C; - C;.; must see writes in C;_; in both E; and E, but may see a different 
write in E; from the one it sees in E. Formally: 


6. For any read rin A; - C;.;, we have hb,(W,(r), r) 
7. For any read rin (C; - C;_7), we have W,(r) in C;_; and W(r) in C;_; 
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Given a set of sufficient synchronizes-with edges for E;, if there is a release-acquire 
pair that happens-before (§17.4.5) an action you are committing, then that pair must 


be present in all E;, where j 2 i. Formally: 


8. 


Let ssw; be the sw; edges that are also in the transitive reduction of hb; but not 
in po. We call ssw; the sufficient synchronizes-with edges for E;. If ssw((x, y) 


and hb,(y, z) and z in C;, then sw,(x, y) for all j 2 7. 


If an action y is committed, all external actions that happen-before y are also 


committed. 


If y is in C;, x is an external action and hb,(x, y), then x in C;. 


Example 17.4.8-1. Happens-before Consistency Is Not Sufficient 


Happens-before consistency is a necessary, but not sufficient, set of constraints. Merely 
enforcing happens-before consistency would allow for unacceptable behaviors - those that 
violate the requirements we have established for programs. For example, happens-before 
consistency allows values to appear "out of thin air". This can be seen by a detailed 
examination of the trace in Table 17.4.8-A. 


Table 17.4.8-A. Happens-before consistency is not sufficient 


Memory Model 


Thread 1 Thread 2 
rl = x; r2 = yi; 
if “(rl h= 0) y= 1; if (r2 != 0) x = 1; 


The code shown in Table 17.4.8-A is correctly synchronized. This may seem surprising, 
since it does not perform any synchronization actions. Remember, however, that a program 
is correctly synchronized if, when it is executed in a sequentially consistent manner, there 
are no data races. If this code is executed in a sequentially consistent way, each action will 
occur in program order, and neither of the writes will occur. Since no writes occur, there 
can be no data races: the program is correctly synchronized. 


Since this program is correctly synchronized, the only behaviors we can allow are 
sequentially consistent behaviors. However, there is an execution of this program that is 
happens-before consistent, but not sequentially consistent: 


rl =x; // sees write of x =1 
y=1; 
r2 = y; // sees write of y = 1 
x = 1; 


This result is happens-before consistent: there is no happens-before relationship that 
prevents it from occurring. However, it is clearly not acceptable: there is no sequentially 
consistent execution that would result in this behavior. The fact that we allow a read to see 
a write that comes later in the execution order can sometimes thus result in unacceptable 
behaviors. 
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Although allowing reads to see writes that come later in the execution order is sometimes 
undesirable, it is also sometimes necessary. As we saw above, the trace in Table 17.4.5- 
A requires some reads to see writes that occur later in the execution order. Since the reads 
come first in each thread, the very first action in the execution order must be a read. If that 
read cannot see a write that occurs later, then it cannot see any value other than the initial 
value for the variable it reads. This is clearly not reflective of all behaviors. 


We refer to the issue of when reads can see future writes as causality, because of issues 
that arise in cases like the one found in Table 17.4.8-A. In that case, the reads cause the 
writes to occur, and the writes cause the reads to occur. There is no "first cause" for the 
actions. Our memory model therefore needs a consistent way of determining which reads 
can see writes early. 


Examples such as the one found in Table 17.4.8-A demonstrate that the specification must 
be careful when stating whether a read can see a write that occurs later in the execution 
(bearing in mind that if a read sees a write that occurs later in the execution, it represents 
the fact that the write is actually performed early). 


The memory model takes as input a given execution, and a program, and determines 
whether that execution is a legal execution of the program. It does this by gradually building 
a set of "committed" actions that reflect which actions were executed by the program. 
Usually, the next action to be committed will reflect the next action that can be performed by 
a sequentially consistent execution. However, to reflect reads that need to see later writes, 
we allow some actions to be committed earlier than other actions that happen-before them. 


Obviously, some actions may be committed early and some may not. If, for example, one of 
the writes in Table 17.4.8-A were committed before the read of that variable, the read could 
see the write, and the "out-of-thin-air" result could occur. Informally, we allow an action to 
be committed early if we know that the action can occur without assuming some data race 
occurs. In Table 17.4.8-A, we cannot perform either write early, because the writes cannot 
occur unless the reads see the result of a data race. 


17.4.9 Observable Behavior and Nonterminating Executions 


For programs that always terminate in some bounded finite period of time, 
their behavior can be understood (informally) simply in terms of their allowable 
executions. For programs that can fail to terminate in a bounded amount of time, 
more subtle issues arise. 


The observable behavior of a program is defined by the finite sets of external 
actions that the program may perform. A program that, for example, simply prints 
"Hello" forever is described by a set of behaviors that for any non-negative integer 
i, includes the behavior of printing "Hello" i times. 


Termination is not explicitly modeled as a behavior, but a program can easily 
be extended to generate an additional external action executionTermination that 
occurs when all threads have terminated. 
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We also define a special hang action. If behavior is described by a set of external 
actions including a hang action, it indicates a behavior where after the external 
actions are observed, the program can run for an unbounded amount of time without 
performing any additional external actions or terminating. Programs can hang if all 
threads are blocked or if the program can perform an unbounded number of actions 
without performing any external actions. 


A thread can be blocked in a variety of circumstances, such as when it is attempting 
to acquire a lock or perform an external action (such as a read) that depends on 
external data. 


An execution may result in a thread being blocked indefinitely and the execution's 
not terminating. In such cases, the actions generated by the blocked thread must 
consist of all actions generated by that thread up to and including the action that 
caused the thread to be blocked, and no actions that would be generated by the 
thread after that action. 


To reason about observable behaviors, we need to talk about sets of observable 
actions. 


If O is aset of observable actions for an execution E, then set O must be a subset of 
E's actions, A, and must contain only a finite number of actions, even if A contains 
an infinite number of actions. Furthermore, if an action y is in O, and either hb(x, 
y) or so(x, y), then x is in O. 


Note that a set of observable actions are not restricted to external actions. Rather, 
only external actions that are in a set of observable actions are deemed to be 
observable external actions. 


A behavior B is an allowable behavior of a program P if and only if B is a finite 
set of external actions and either: 


e There exists an execution E of P, and a set O of observable actions for E, and B 
is the set of external actions in O (If any threads in E end in a blocked state and 
O contains all actions in F, then B may also contain a hang action); or 


¢ There exists a set O of actions such that B consists of a hang action plus all the 
external actions in O and for all k =| O|, there exists an execution E of P with 
actions A, and there exists a set of actions O' such that: 


— Both O and O' are subsets of A that fulfill the requirements for sets of 
observable actions. 


~OCO'CA 
~|O'|2k 
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— O'- O contains no external actions 


Note that a behavior B does not describe the order in which the external actions in B are 
observed, but other (internal) constraints on how the external actions are generated and 
performed may impose such constraints. 


17.5 final Field Semantics 


Fields declared final are initialized once, but never changed under normal 
circumstances. The detailed semantics of final fields are somewhat different from 
those of normal fields. In particular, compilers have a great deal of freedom to 
move reads of final fields across synchronization barriers and calls to arbitrary or 
unknown methods. Correspondingly, compilers are allowed to keep the value of a 
final field cached in a register and not reload it from memory in situations where 
a non-final field would have to be reloaded. 


final fields also allow programmers to implement thread-safe immutable objects 
without synchronization. A thread-safe immutable object is seen as immutable 
by all threads, even if a data race is used to pass references to the immutable 
object between threads. This can provide safety guarantees against misuse of an 
immutable class by incorrect or malicious code. final fields must be used correctly 
to provide a guarantee of immutability. 


An object is considered to be completely initialized when its constructor finishes. A 
thread that can only see a reference to an object after that object has been completely 
initialized is guaranteed to see the correctly initialized values for that object's final 
fields. 


The usage model for final fields is a simple one: Set the final fields for an 
object in that object's constructor; and do not write a reference to the object being 
constructed in a place where another thread can see it before the object's constructor 
is finished. If this is followed, then when the object is seen by another thread, that 
thread will always see the correctly constructed version of that object's final fields. 
It will also see versions of any object or array referenced by those final fields that 
are at least as up-to-date as the final fields are. 


Example 17.5-1. final Fields In The Java Memory Model 


The program below illustrates how final fields compare to normal fields. 


class FinalFieldExample { 
final int x; 
int y; 
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static FinalFieldExample f; 


public FinalFieldExample() { 


x 3.33 
y= 4; 
} 
static void writer() { 


f = new FinalFieldExample(); 


static void reader() { 
if (£ != null) { 
int i= f£f.x; // guaranteed to see 3 


int j = f.y; // could see 0 


The class FinalFieldExample has a final int field x and anon-final int field y. One 
thread might execute the method writer and another might execute the method reader. 


Because the writer method writes £ after the object's constructor finishes, the reader 
method will be guaranteed to see the properly initialized value for f.x: it will read the 
value 3. However, f.y is not final; the reader method is therefore not guaranteed to 
see the value 4 for it. 


Example 17.5-2. final Fields For Security 


final fields are designed to allow for necessary security guarantees. Consider the 
following program. One thread (which we shall refer to as thread 1) executes: 


Global.s = "/tmp/usr".substring (4); 
while another thread (thread 2) executes 


String myS = Global.s; 
if (myS.equals("/tmp") )System.out.printin(myS) ; 


String objects are intended to be immutable and string operations do not perform 
synchronization. While the String implementation does not have any data races, other 
code could have data races involving the use of String objects, and the memory model 
makes weak guarantees for programs that have data races. In particular, if the fields of the 
String class were not final, then it would be possible (although unlikely) that thread 2 
could initially see the default value of 0 for the offset of the string object, allowing it to 
compare as equal to "/tmp". A later operation on the String object might see the correct 
offset of 4, so that the String object is perceived as being "/usr". Many security features 
of the Java programming language depend upon String objects being perceived as truly 
immutable, even if malicious code is using data races to pass String references between 
threads. 
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17.5.1 Semantics of finai Fields 


Let o be an object, and c be a constructor for o in which a final field fis written. 
A freeze action on final field f of o takes place when c exits, either normally or 
abruptly. 


Note that if one constructor invokes another constructor, and the invoked 
constructor sets a final field, the freeze for the final field takes place at the end 
of the invoked constructor. 


For each execution, the behavior of reads is influenced by two additional partial 
orders, the dereference chain dereferences() and the memory chain mc(), which are 
considered to be part of the execution (and thus, fixed for any particular execution). 
These partial orders must satisfy the following constraints (which need not have 
a unique solution): 


¢ Dereference Chain: If an action a is a read or write of a field or element of an 
object o by a thread ¢ that did not initialize o, then there must exist some read r 
by thread ¢ that sees the address of o such that r dereferences(r, a). 


¢ Memory Chain: There are several constraints on the memory chain ordering: 
— If ris a read that sees a write w, then it must be the case that mc(w, r). 


— If rand a are actions such that dereferences(r, a), then it must be the case that 
mc(r, a). 


— If wis a write of the address of an object o by a thread ¢ that did not initialize 
o, then there must exist some read r by thread ¢ that sees the address of o such 
that mc(r, w). 


Given a write w, a freeze f, an action a (that is not a read of a final field), a read 
r; of the final field frozen by f, and a read rz such that hb(w, f), hb(f, a), mc(a, r1), 
and dereferences(r;, r2), then when determining which values can be seen by r2, 
we consider hb(w, rz). (This happens-before ordering does not transitively close 
with other happens-before orderings.) 


Note that the dereferences order is reflexive, and r; can be the same as rp. 


For reads of final fields, the only writes that are deemed to come before the read 
of the final field are the ones derived through the final field semantics. 


17.5.2 Reading final Fields During Construction 


A read of a final field of an object within the thread that constructs that object is 
ordered with respect to the initialization of that field within the constructor by the 
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usual happens-before rules. If the read occurs after the field is set in the constructor, 
it sees the value the final field is assigned, otherwise it sees the default value. 


17.5.3 Subsequent Modification of £ina1 Fields 


In some cases, such as deserialization, the system will need to change the final 
fields of an object after construction. final fields can be changed via reflection 
and other implementation-dependent means. The only pattern in which this has 
reasonable semantics is one in which an object is constructed and then the final 
fields of the object are updated. The object should not be made visible to other 
threads, nor should the final fields be read, until all updates to the final fields 
of the object are complete. Freezes of a final field occur both at the end of the 
constructor in which the final field is set, and immediately after each modification 
of a final field via reflection or other special mechanism. 


Even then, there are a number of complications. If a final field is initialized to 
a constant expression ($15.28) in the field declaration, changes to the final field 
may not be observed, since uses of that final field are replaced at compile time 
with the value of the constant expression. 


Another problem is that the specification allows aggressive optimization of final 
fields. Within a thread, it is permissible to reorder reads of a final field with those 
modifications of a final field that do not take place in the constructor. 


Example 17.5.3-1. Aggressive Optimization of £ina1 Fields 


class A { 
final int x; 


A() { 

Sn dey 
} 
int f() { 


return d(this,this) ; 
} 


int d(A al, A a2) { 


int i = al.x; 
g(al); 

int j = a2.x; 
return j - i; 


} 
static void g(A a) { 


// uses reflection to change a.x to 2 


} 
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In the d method, the compiler is allowed to reorder the reads of x and the call to g freely. 
Thus, new A().£() could return -1, 0, or 1. 


An implementation may provide a way to execute a block of code in a final-field- 
safe context. If an object is constructed within a fina1l-field-safe context, the reads 
of a final field of that object will not be reordered with modifications of that final 
field that occur within that fina1-field-safe context. 


A final-field-safe context has additional protections. If a thread has seen an 
incorrectly published reference to an object that allows the thread to see the default 
value of a final field, and then, within a final-field-safe context, reads a properly 
published reference to the object, it will be guaranteed to see the correct value of 
the final field. In the formalism, code executed within a final-field-safe context 
is treated as a separate thread (for the purposes of final field semantics only). 


In an implementation, a compiler should not move an access to a final field into 
or out of a final-field-safe context (although it can be moved around the execution 
of such a context, so long as the object is not constructed within that context). 


One place where use of a final-field-safe context would be appropriate is in an executor 
or thread pool. By executing each Runnable in a separate final-field-safe context, the 
executor could guarantee that incorrect access by one Runnable to a object o will not 
remove final field guarantees for other Runnables handled by the same executor. 


17.5.4 Write-Protected Fields 


Normally, a field that is final and static may not be modified. However, 
System.in, System.out, and System.err are static final fields that, for 
legacy reasons, must be allowed to be changed by the methods system.setIn, 
System.setOut, and System.setErr. We refer to these fields as being write- 
protected to distinguish them from ordinary final fields. 


The compiler needs to treat these fields differently from other final fields. For 
example, a read of an ordinary final field is "Immune" to synchronization: the 
barrier involved in a lock or volatile read does not have to affect what value is read 
from a final field. Since the value of write-protected fields may be seen to change, 
synchronization events should have an effect on them. Therefore, the semantics 
dictate that these fields be treated as normal fields that cannot be changed by user 
code, unless that user code is in the system class. 
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17.6 Word Tearing 


One consideration for implementations of the Java Virtual Machine is that every 
field and array element is considered distinct; updates to one field or element must 
not interact with reads or updates of any other field or element. In particular, two 
threads that update adjacent elements of a byte array separately must not interfere 
or interact and do not need synchronization to ensure sequential consistency. 


Some processors do not provide the ability to write to a single byte. It would be 
illegal to implement byte array updates on such a processor by simply reading an 
entire word, updating the appropriate byte, and then writing the entire word back to 
memory. This problem is sometimes known as word tearing, and on processors that 
cannot easily update a single byte in isolation some other approach will be required. 


Example 17.6-1. Detection of Word Tearing 


The following program is a test case to detect word tearing: 


public class WordTearing extends Thread { 
static final int LENGTH = 8; 
static final int ITERS = 1000000; 
static byte[] counts = new byte[LENGTH]; 
static Thread[] threads = new Thread[LENGTH]; 


final int id; 
WordTearing(int i) { 
id = i; 


} 


public void run() { 
byte v = 0; 
for (int i = 0; i < ITERS; itt) { 
byte v2 = counts[id]; 


if (v != v2) { 
System.err.println("Word-Tearing found: " + 
"counts[" + id + "J = "4+ v2 4+ 
", should be " + v); 
return; 
} 
vt+; 
counts[id] = v; 


} 


public static void main(String[] args) { 
for (int i = 0; i < LENGTH; ++i) 
(threads[i] = new WordTearing(i)).start(); 
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This makes the point that bytes must not be overwritten by writes to adjacent bytes. 


17.7 Non-Atomic Treatment of double and long 


For the purposes of the Java programming language memory model, a single write 
to a non-volatile Long or double value is treated as two separate writes: one to each 
32-bit half. This can result in a situation where a thread sees the first 32 bits of a 
64-bit value from one write, and the second 32 bits from another write. 


Writes and reads of volatile long and double values are always atomic. 


Writes to and reads of references are always atomic, regardless of whether they are 
implemented as 32-bit or 64-bit values. 


Some implementations may find it convenient to divide a single write action on a 64-bit 
long or double value into two write actions on adjacent 32-bit values. For efficiency's 
sake, this behavior is implementation-specific; an implementation of the Java Virtual 
Machine is free to perform writes to Long and double values atomically or in two parts. 


Implementations of the Java Virtual Machine are encouraged to avoid splitting 64-bit values 
where possible. Programmers are encouraged to declare shared 64-bit values as volatile 
or synchronize their programs correctly to avoid possible complications. 
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Type Inference 


A variety of compile-time analyses require reasoning about types that are not yet 
known. Principal among these are generic method applicability testing ($18.5.1) 
and generic method invocation type inference (§18.5.2). In general, we refer to the 
process of reasoning about unknown types as type inference. 


At a high level, type inference can be decomposed into three processes: 


Reduction takes a compatibility assertion about an expression or type, called 
a constraint formula, and reduces it to a set of bounds on inference variables. 
Often, a constraint formula reduces to other constraint formulas, which must 
be recursively reduced. A procedure is followed to identify these additional 
constraint formulas and, ultimately, to express via a bound set the conditions 
under which the choices for inferred types would render each constraint formula 
true. 


Incorporation maintains a set of inference variable bounds, ensuring that these 
are consistent as new bounds are added. Because the bounds on one variable 
can sometimes impact the possible choices for another variable, this process 
propagates bounds between such interdependent variables. 


Resolution examines the bounds on an inference variable and determines an 
instantiation that is compatible with those bounds. It also decides the order in 
which interdependent inference variables are to be resolved. 


These processes interact closely: reduction can trigger incorporation; incorporation 
may lead to further reduction; and resolution may cause further incorporation. 


§18.1 more precisely defines the concepts used as intermediate results and the 
notation used to express them. 


$18.2 describes reduction in detail. 


§18.3 describes incorporation in detail. 
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¢ §18.4 describes resolution in detail. 


¢ §18.5 defines how these inference tools are used to solve certain compile-time 
analysis problems. 


In comparison to the Java SE 7 Edition of The Java® Language Specification, important 
changes to inference include: 


e Adding support for lambda expressions and method references as method invocation 
arguments. 


* Generalizing to define inference in terms of poly expressions, which may not have well- 
defined types until after inference is complete. This has the notable effect of improving 
inference for nested generic method and diamond constructor invocations. 


¢ Describing how inference is used to handle wildcard-parameterized functional interface 
target types and most specific method analysis. 


¢ Clarifying the distinction between invocation applicability testing (which involves only 
the invocation arguments) and invocation type inference (which incorporates a target 


type). 
¢ Delaying resolution of all inference variables, even those with lower bounds, until 
invocation type inference, in order to get better results. 


¢ Improving inference behavior for interdependent (or self-dependent) variables. 


¢ Eliminating bugs and potential sources of confusion. This revision more carefully and 
precisely handles the distinction between specific conversion contexts and subtyping, 
and describes reduction by paralleling the corresponding non-inference relations. Where 
there are intentional departures from the non-inference relations, these are explicitly 
identified as such. 


¢ Laying a foundation for future evolution: enhancements to or new applications of 
inference will be easier to integrate into the specification. 


18.1 Concepts and Notation 


This section defines inference variables, constraint formulas, and bounds, as the 
terms will be used throughout this chapter. It also presents notation. 


18.1.1 Inference Variables 


Inference variables are meta-variables for types - that is, they are special names 
that allow abstract reasoning about types. To distinguish them from type variables, 
inference variables are represented with Greek letters, principally a. 


The term "type" is used loosely in this chapter to include type-like syntax 
that contains inference variables. The term proper type excludes such "types" 
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that mention inference variables. Assertions that involve inference variables are 
assertions about every proper type that can be produced by replacing each inference 
variable with a proper type. 


18.1.2 Constraint Formulas 


Constraint formulas are assertions of compatibility or subtyping that may involve 
inference variables. The formulas may take one of the following forms: 


e <Expression — T>: An expression is compatible in a loose invocation context 
with type 7 (§5.3). 


* <s— mp: A type sis compatible in a loose invocation context with type rT (§5.3). 
* <s<: DP: A reference type s is a subtype of a reference type r ($4.10). 
* <s<= p>: A type argument s is contained by a type argument rT (§4.5.1). 


*¢ <s= TD: A type s is the same as a type T (§4.3.4), or a type argument s is the 
same as type argument r. 


¢ <LambdaExpression > throws T>: The checked exceptions thrown by the body of 


the LambdaExpression are declared by the throws clause of the function type 
derived from r. 


¢ <MethodReference > throws T>: The checked exceptions thrown by the referenced 
method are declared by the throws clause of the function type derived from r. 


Examples of constraint formulas: 
¢ From Collections.singleton ("hi"), we have the constraint formula <"hi" > ®. 


Through reduction, this will become the constraint formula: <St ring <: Q. 


¢ From Arrays.asList (1, 2.0), we have the constraint formulas <1 — a and «2.0 
— o. Through reduction, these will become the constraint formulas <int — o» and 
<double > , and then <Integer <: O and «Double <: @. 


¢ From the target type of the constructor invocation List<Thread> 1t = new 
ArrayList<>(), we have the constraint formula <ArrayList<Q@> — List<Thread>>. 
Through reduction, this will become the constraint formula <a <= Thread>, and then 
<O = Thread>. 


18.1.3. Bounds 


During the inference process, a set of bounds on inference variables is maintained. 
A bound has one of the following forms: 


¢ s=T, where at least one of s or Tis an inference variable: s is the same as T. 
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¢ s<: T, where at least one of s or Tis an inference variable: s is a subtype of rT. 
¢ false: No valid choice of inference variables exists. 


* G<Q;, ..., M,> = capture(G<A), ..., A,>): The variables 01;, ..., &, represent the result 
of capture conversion (§5.1.10) applied to <A, ..., A,> (where Aj, ..., A, may be 
types or wildcards and may mention inference variables). 


* throws Ot: The inference variable & appears in a throws clause. 


A bound is satisfied by an inference variable substitution if, after applying the 
substitution, the assertion is true. The bound false can never be satisfied. 


Some bounds relate an inference variable to a proper type. Let r be a proper type. 
Given a bound of the form & = Tor T=Q, we say Tis an instantiation of . Similarly, 
given a bound of the form @ <: T, we say Tis a proper upper bound of , and given 
a bound of the form Tr <: Q, we say T is a proper lower bound of a. 


Other bounds relate two inference variables, or an inference variable to a type that 
contains inference variables. Such bounds, of the form s= Tor s <: T, are called 
dependencies. 


A bound of the form G<Q;, ..., &,> = capture(G<A), ..., An>) indicates that O;, ..., On 
are placeholders for the results of capture conversion. This is necessary because 
capture conversion can only be performed on a proper type, and the inference 
variables in Aj, ..., A, May not yet be resolved. 


A bound of the form throws @ is purely informational: it directs resolution to 
optimize the instantiation of o so that, if possible, it is not a checked exception type. 


An important intermediate result of inference is a bound set. It is sometimes 
convenient to refer to an empty bound set with the symbol true; this is merely out 
of convenience, and the two are interchangeable. 


Examples of bound sets: 


* {Q=String } contains a single bound, instantiating © as String. 


* { Integer <: Q, Double <: ,Q@<: Object } describes two proper lower bounds and 
one proper upper bound for a. 


* {Q<: Iterable<?>, B <: Object, @<: List<P> } describes a proper upper bound 
for each of o and B, along with a dependency between them. 


¢ { } contains no bounds nor dependencies, and can be referred to as true. 


¢ { false } expresses the fact that no satisfactory instantiation exists. 
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When inference begins, a bound set is typically generated from a list of type 
parameter declarations P;, ..., Pp and associated inference variables 0;, ..., &,. Such 
a bound set is generated as follows. For each / (1 </ <p): 


¢ If p, has no TypeBound, the bound &, <: Object appears in the set. 


¢ Otherwise, for each type r delimited by « in the TypeBound, the bound Q,; <: 
T[P1!=Q, ..., Pp:=Q,] appears in the set; if this results in no proper upper bounds 
for &, (only dependencies), then the bound @; <: Object also appears in the set. 


18.2 Reduction 


Reduction is the process by which a set of constraint formulas (§18.1.2) is 
simplified to produce a bound set (§18.1.3). 


Each constraint formula is considered in turn. The rules in this section specify how 
the formula is reduced to one or both of: 


¢ A bound or bound set, which is to be incorporated with the "current" bound set. 
Initially, the current bound set is empty. 


¢ Further constraint formulas, which are to be reduced recursively. 


Reduction completes when no further constraint formulas remain to be reduced. 


The results of a reduction step are always soundness-preserving: if an inference variable 
instantiation satisfies the reduced constraints and bounds, it will also satisfy the original 
constraint. On the other hand, reduction is not completeness-preserving: there may exist 
inference variable instantiations that satisfy the original constraint but do not satisfy a 
reduced constraint or bound. This is due to inherent limitations of the algorithm, along with 
a desire to avoid undue complexity. One effect is that there are expressions for which type 
argument inference fails to find a solution, but that can be well-typed if the programmer 
explicitly inserts appropriate types. 


18.2.1 Expression Compatibility Constraints 


A constraint formula of the form <Expression > T is reduced as follows: 


¢ If ris a proper type, the constraint reduces to true if the expression is compatible 
in a loose invocation context with rT (§5.3), and false otherwise. 


¢ Otherwise, if the expression is a standalone expression (§15.2) of type s, the 
constraint reduces to <s > PD. 


¢ Otherwise, the expression is a poly expression (§15.2). The result depends on 
the form of the expression: 
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— If the expression is a parenthesized expression of the form ( Expression’ ), the 


constraint reduces to <Expression' > T. 


— If the expression is a class instance creation expression or a method invocation 


expression, the constraint reduces to the bound set B; which would be used 
to determine the expression's compatibility with target type 1, as defined 
in §18.5.2.1. (For a class instance creation expression, the corresponding 
"method" used for inference is defined in §15.9.3.) 


This bound set may contain new inference variables, as well as dependencies 
between these new variables and the inference variables in rT. 


— If the expression is a conditional expression of the form e; ? e2 : e3, the 


constraint reduces to two constraint formulas, <e, > m and <e; > 7. 


— If the expression is a lambda expression or a method reference expression, the 


result is specified below. 


By treating nested generic method invocations as poly expressions, we improve the 
behavior of inference for nested invocations. For example, the following is illegal in Java 
SE 7 but legal in Java SE 8: 


ProcessBuilder b = new ProcessBuilder(Collections.emptyList ()); 
// ProcessBuilder's constructor expects a List<String> 


When both the outer and the nested invocation require inference, the problem is more 
difficult. For example: 


List<String> ls = new ArrayList<>(Collections.emptyList ()); 


Our approach is to "lift" the bounds inferred for the nested invocation (simply { @ <: 
Object } in the case of empt yList) into the outer inference process (in this case, trying 


to infer B where the constructor is for type ArrayList<f>). We also infer dependencies 
between the nested inference variables and the outer inference variables (the constraint 


<List<Q@> — Collection<fB>> would reduce to the dependency o = §). In this way, 
resolution of the inference variables in the nested invocation can wait until additional 


information can be inferred from the outer invocation (based on the assignment target, B 
= String). 


A constraint formula of the form <LambdaExpression + T, where T mentions at 
least one inference variable, is reduced as follows: 


¢ If ris not a functional interface type ($9.8), the constraint reduces to false. 


¢ Otherwise, let r' be the ground target type derived from 1, as specified in 


§15.27.3. If §18.5.3 is used to derive a functional interface type which is 
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parameterized, then the test that r<A'), ..., A'n> iS a Subtype of F<A, ..., An> 1S 
not performed (instead, it is asserted with a constraint formula below). Let the 
target function type for the lambda expression be the function type of r'. Then: 


— If no valid function type can be found, the constraint reduces to false. 


— Otherwise, the congruence of LambdaExpression with the target function type 
is asserted as follows: 


>» If the number of lambda parameters differs from the number of parameter 
types of the function type, the constraint reduces to false. 


>» Ifthe lambda expression is implicitly typed and one or more of the function 
type's parameter types is not a proper type, the constraint reduces to false. 


This condition never arises in practice, due to the handling of implicitly typed 
lambda expressions in §18.5.1 and the substitution applied to the target type in 
§18.5.2.2. 
>» If the function type'’s result is void and the lambda body is neither a 
statement expression nor a void-compatible block, the constraint reduces to 
false. 


>» If the function type's result is not void and the lambda body is a block that 
is not value-compatible, the constraint reduces to false. 


» Otherwise, the constraint reduces to all of the following constraint formulas: 


» If the lambda parameters have explicitly declared types F;, ..., F, and the 
function type has parameter types Gi, ..., Gp, then (i) for alli(1 <i <n), 
<F; = G», and (ii) <T' <: PD. 


» If the function type's return type is a (non-void) type R, assume the 
lambda's parameter types are the same as the function type's parameter 
types. Then: 


¢ If Ris a proper type, and if the lambda body or some result expression 
in the lambda body is not compatible in an assignment context with rR, 
then false. 


¢ Otherwise, if Ris not a proper type, then where the lambda body has the 
form Expression, the constraint <Expression + R»>; or where the lambda 
body is a block with result expressions e, ..., e,, for alli(1 <i < m), 
<e; OR. 


The key piece of information to derive from a compatibility constraint involving a lambda 
expression is the set of bounds on inference variables appearing in the target function 
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type's return type. This is crucial, because functional interfaces are often generic, and many 
methods operating on these types are generic, too. 


In the simplest case, a lambda expression may simply provide a lower bound for an 
inference variable: 


<T> List<T> makeThree(Factory<T> factory) { ... } 
String s = makeThree(() -> "abc").get (2); 


In more complex cases, a result expression may be a poly expression - perhaps even 
another lambda expression - and so the inference variable might be passed through multiple 
constraint formulas with different target types before a bound is produced. 


Most of the work described in this section precedes assertions about the result expressions; 
its purpose is to derive the lambda expression's function type, and to check for expressions 
that are clearly disqualified from compatibility. 


We do not attempt to produce bounds on inference variables that appear in the target 
function type's throws clause. This is because exception containment is not part of 
compatibility (§ 15.27.3) - in particular, it must not influence method applicability (§18.5.1). 
However, we do get bounds on these variables later, because invocation type inference 
(§18.5.2.2) produces exception containment constraint formulas (§18.2.5). 


Note that if the target type is an inference variable, or if the target type's parameter types 
contain inference variables, we produce false. During invocation type inference (§18.5.2.2), 
extra substitutions are performed in order to instantiate these inference variables, thus 
avoiding this scenario. (In other words, reduction will, in practice, never be "invoked" with 
a target type of one of these forms.) 


Finally, note that the result expressions of a lambda expression are required by §15.27.3 
to be compatible in an assignment context with the target type's return type, R. If R 


is a proper type, such as Byte derived from Function<a, Byte>, then assignability is 
easy enough to test, and reduction does so above. If R is not a proper type, such as 


derived from Function<String, a>, then we make the simplifying assumption above 
that loose invocation compatibility will be sufficient. The difference between assignment 
compatibility and loose invocation compatibility is that only assignment allows narrowing 
of constant expressions, such as Byte b = 100;. Consequently, our simplifying 


assumption is not completeness-preserving: given target return type o and an integer literal 


result expression 100, it is conceivable that a could be instantiated to Byte, but reduction 
will not in fact produce such a bound. 


A constraint formula of the form <MethodReference — ™, where T mentions at 
least one inference variable, is reduced as follows: 


¢ If ris not a functional interface type, or if ris a functional interface type that 
does not have a function type (§9.9), the constraint reduces to false. 


¢ Otherwise, if there does not exist a potentially applicable method for the method 
reference when targeting r, the constraint reduces to false. 
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¢ Otherwise, if the method reference is exact (§15.13.1), then let P;, ..., P, be the 
parameter types of the function type of 7, and let Fj, ..., F, be the parameter 
types of the potentially applicable method. The constraint reduces to a new set 
of constraints, as follows: 


— In the special case where n = k+1, the parameter of type P; is to act as the target 
reference of the invocation. The method reference expression necessarily 
has the form ReferenceType :: [TypeArguments] Identifier. The constraint 
reduces to <P; <: ReferenceType> and, for all i (2 <i<n), <P; > Fy_p. 


In all other cases, n = k, and the constraint reduces to, for all i (1 Si <n), 
<Pi DO Fp. 


— Ifthe function type's result is not void, let R be its return type. Then, if the result 
of the potentially applicable compile-time declaration is void, the constraint 
reduces to false. Otherwise, the constraint reduces to <r’ 4 R», where R' is 
the result of applying capture conversion (§5.1.10) to the return type of the 
potentially applicable compile-time declaration. 


¢ Otherwise, the method reference is inexact, and: 


— If one or more of the function type's parameter types is not a proper type, the 
constraint reduces to false. 


This condition never arises in practice, due to the handling of inexact method 
references in §18.5.1 and the substitution applied to the target type in §18.5.2.2. 


— Otherwise, a search for a compile-time declaration is performed, as specified 
in §15.13.1. If there is no compile-time declaration for the method reference, 
the constraint reduces to false. Otherwise, there is a compile-time declaration, 
and: (let R be the result of the function type) 


> If Ris void, the constraint reduces to true. 


» Otherwise, if the method reference expression elides TypeArguments, and 
the compile-time declaration is a generic method, and the return type of 
the compile-time declaration mentions at least one of the method's type 
parameters, then: 


» If R mentions one of the type parameters of the function type, the 
constraint reduces to false. 


In this case, a constraint in terms of R might lead an inference variable to be 
bound by an out-of-scope type variable. Since instantiating an inference variable 
with an out-of-scope type variable is nonsensical, we prefer to avoid the situation 
by giving up immediately whenever the possibility arises. This simplification is 
not completeness-preserving. 
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» If R does not mention one of the type parameters of the function type, 
then the constraint reduces to the bound set 8; which would be used to 
determine the method reference's compatibility when targeting the return 
type of the function type, as defined in §18.5.2.1. B; may contain new 
inference variables, as well as dependencies between these new variables 
and the inference variables in rT. 


The strategy used to determine a return type for a generic referenced method 
follows the pattern used earlier in this section for generic method invocations. 
This may involve "lifting" bounds into the outer context and inferring 
dependencies between the two sets of inference variables. 
>» Otherwise, let R' be the result of applying capture conversion (§5.1.10) 
to the return type of the invocation type (§15.12.2.6) of the compile-time 
declaration. If R' is void, the constraint reduces to false; otherwise, the 
constraint reduces to <r’ > R. 


18.2.2. Type Compatibility Constraints 


A constraint formula of the form <s > 7 is reduced as follows: 


If s and rare proper types, the constraint reduces to true if s is compatible in a 
loose invocation context with r (§5.3), and false otherwise. 


Otherwise, if s is a primitive type, let s' be the result of applying boxing 
conversion (§5.1.7) to s. Then the constraint reduces to <s' > >. 


Otherwise, if T is a primitive type, let r' be the result of applying boxing 
conversion (§5.1.7) to r. Then the constraint reduces to <s = T. 


Otherwise, if Tis a parameterized type of the form G<Tj, ..., T,>, and there exists 
no type of the form c<...> that is a supertype of s, but the raw type Gis a supertype 
of s, then the constraint reduces to true. 


Otherwise, if Tis an array type of the form G<Tj, ..., T,»>[] KE and there exists no 
type of the form G<...> (1* that is a supertype of s, but the raw type etkisa 
supertype of s, then the constraint reduces to true. (The notation (1 indicates 
an array type of & dimensions.) 


Otherwise, the constraint reduces to <S <: T». 


The fourth and fifth cases are implicit uses of unchecked conversion (§5.1.9). 
These, along with any use of unchecked conversion in the first case, may result in 
compile-time unchecked warnings, and may influence a method's invocation type 
($15.12.2.6). 


TYPE INFERENCE Reduction 


Boxing T to T' is not completeness-preserving; for example, if T were long, S might be 
instantiated to Integer, which is not a subtype of Long but could be unboxed and then 
widened to long. We avoid this problem in most cases by giving special treatment to 
inference-variable return types that we know are already constrained to be certain boxed 
primitive types; see §18.5.2.1. 


Similarly, the treatment of unchecked conversion sacrifices completeness in cases in which 
T is not a parameterized type (for example, if Tis an inference variable). It is not usually 
clear in such situations whether the unchecked conversion is necessary or not. Since 
unchecked conversions introduce unchecked warnings, inference prefers to avoid them 
unless it is clearly necessary. 


18.2.3. Subtyping Constraints 


A constraint formula of the form <s <: 7 is reduced as follows: 


If s and r are proper types, the constraint reduces to true if s is a subtype of T 
(§4.10), and false otherwise. 


Otherwise, if s is the null type, the constraint reduces to true. 
Otherwise, if 7 is the null type, the constraint reduces to false. 


Otherwise, if s is an inference variable, o, the constraint reduces to the bound 
Q<: T. 


Otherwise, if Tis an inference variable, o, the constraint reduces to the bound 
S<: Q. 


Otherwise, the constraint is reduced according to the form of T: 


— If ris a parameterized class or interface type, or an inner class type of a 
parameterized class or interface type (directly or indirectly), let aj, ..., A, be 
the type arguments of r. Among the supertypes of s, a corresponding class 
or interface type is identified, with type arguments 8, ..., B,. If no such type 
exists, the constraint reduces to false. Otherwise, the constraint reduces to the 
following new constraints: for all i (1 <i <n), <B; <= Ap. 


— If ris any other class or interface type, then the constraint reduces to true if T 
is among the supertypes of s, and false otherwise. 


— If ris an array type, r'[], then among the supertypes of s that are array types, 
a most specific type is identified, s'[] (this may be s itself). If no such array 
type exists, the constraint reduces to false. Otherwise: 


>» Ifneither s' nor T' is a primitive type, the constraint reduces to <s'<: T". 


» Otherwise, the constraint reduces to true if s' and r' are the same primitive 
type, and false otherwise. 
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— If ris a type variable, there are three cases: 


>» If sis an intersection type of which ris an element, the constraint reduces 
to true. 


>» Otherwise, if rT has a lower bound, B, the constraint reduces to <s <: B. 
» Otherwise, the constraint reduces to false. 


— If ris an intersection type, I; & ... & Ip, the constraint reduces to the following 
new constraints: for alli(1 <i<n),<s<: Ip. 


A constraint formula of the form <s <= 1m, where s and r are type arguments 
(§4.5.1), is reduced as follows: 


¢ If ris a type: 
— If sis a type, the constraint reduces to <s = 1. 
— If sis a wildcard, the constraint reduces to false. 
¢ If ris a wildcard of the form ?, the constraint reduces to true. 
¢ If ris a wildcard of the form ? extends Tr’: 
— If sis a type, the constraint reduces to <s <: T'. 
— If sis a wildcard of the form ?, the constraint reduces to <object <: T". 
— If sis awildcard of the form ? extends s', the constraint reduces to<s'<: T’>. 


— If sis a wildcard of the form ? super s', the constraint reduces to <object 
— eh 


e If ris a wildcard of the form ? super T': 
— If sis a type, the constraint reduces to <T' <: 5. 
— If sis a wildcard of the form ? super s', the constraint reduces to <T' <: S'>. 


— Otherwise, the constraint reduces to false. 


18.2.4 Type Equality Constraints 


A constraint formula of the form <s = m, where s and rT are types, is reduced as 
follows: 


¢ If s and rare proper types, the constraint reduces to true if s is the same as T 
(§4.3.4), and false otherwise. 


¢ Otherwise, if s or Tis the null type, the constraint reduces to false. 
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Otherwise, if s is an inference variable, a, and Tr is not a primitive type, the 
constraint reduces to the bound @ = T. 


Otherwise, if T is an inference variable, , and s is not a primitive type, the 
constraint reduces to the bound s= a. 


Otherwise, if s and rare class or interface types with the same erasure, where s 
has type arguments 8), ..., B, and T has type arguments Aj, ..., A,, the constraint 
reduces to the following new constraints: for all i(1 <i<n), <B; = A,. 


Otherwise, if s and 7 are array types, s'[{] and r'[], the constraint reduces to 
<S'=T". 


Otherwise, if s and rf are intersection types, a correspondence between the 
elements of s and the elements of r is established. An element of s, sj, 
corresponds to an element of 1, 7,, if s; and 1, are either the same type, or both 
parameterizations of the same generic class or interface, or both array types. 


If each element of s corresponds to exactly one element of r, and vice versa, 
then the constraint reduces to the following new constraints: for each element 
s; of s and the corresponding element 1; of 1, <s; = 7T;. If not, the constraint 
reduces to false. 


This rule does not accommodate inference variables appearing directly as elements of 
an intersection type (rather than nested in a parameterized type). Due to the restrictions 
on type parameter declarations (§4.4), such intersection types do not arise in practice. 


Otherwise, the constraint reduces to false. 


A constraint formula of the form <s= m, where s and rare type arguments (§4.5.1), 
is reduced as follows: 


If s and rare types, the constraint is reduced as described above. 
If s has the form ? and rT has the form ?, the constraint reduces to true. 


If s has the form ? and rT has the form ? extends T’, the constraint reduces to 
<Object =T’>. 


If s has the form ? extends s' and T has the form ?, the constraint reduces to 
<S'=Object>. 


If shas the form ? extends s' and rhas the form ? extends T’, the constraint 
reduces to <s'=T">. 


If shas the form ? super s' and rhas the form ? super T', the constraint reduces 
to<s'=T". 


Otherwise, the constraint reduces to false. 
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18.2.5 Checked Exception Constraints 


A constraint formula of the form <LambdaExpression —pyows T> is reduced as 
follows: 


¢ If ris not a functional interface type ($9.8), the constraint reduces to false. 


¢ Otherwise, let the target function type for the lambda expression be determined 
as specified in §15.27.3. If no valid function type can be found, the constraint 
reduces to false. 


¢ Otherwise, if the lambda expression is implicitly typed, and one or more of the 
function type's parameter types is not a proper type, the constraint reduces to 
false. 


This condition never arises in practice, due to the substitution applied to the target type 
in §18.5.2.2. 
¢ Otherwise, if the function type's return type is neither void nor a proper type, 
the constraint reduces to false. 


This condition never arises in practice, due to the substitution applied to the target type 
in §18.5.2.2. 
¢ Otherwise, let £;, ..., E, be the types in the function type's throws clause that are 

not proper types. If the lambda expression is implicitly typed, let its parameter 
types be the function type's parameter types. If the lambda body is a poly 
expression or a block containing a poly result expression, let the targeted return 
type be the function type's return type. Let x;, ..., Xm be the checked exception 
types that the lambda body can throw (§11.2). Then there are two cases: 


— Ifn=o (the function type's throws clause consists only of proper types), then 
if there exists some i (1 Si <m) such that x; is not a subtype of any proper type 
in the throws clause, the constraint reduces to false; otherwise, the constraint 
reduces to true. 


— Ifn> 0, the constraint reduces to a set of subtyping constraints: for all i (1 < 
i<m), if x; is not a subtype of any proper type in the throws clause, then the 
constraints include, for all j (1 <j <n), <x; <: £;. In addition, for all 7 (1 <j 
<n), the constraint reduces to the bound throws £;. 


A constraint formula of the form <MethodReference —yhyows T is reduced as 
follows: 


¢ If ris not a functional interface type, or if 7 is a functional interface type but 
does not have a function type (§9.9), the constraint reduces to false. 
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¢ Otherwise, let the target function type for the method reference expression be 
the function type of r. If the method reference is inexact (§15.13.1) and one or 
more of the function type’s parameter types is not a proper type, the constraint 
reduces to false. 


¢ Otherwise, if the method reference is inexact and the function type's result is 
neither void nor a proper type, the constraint reduces to false. 


¢ Otherwise, let Z,, ..., E, be the types in the function type's throws clause that 
are not proper types. Let x), ..., Xn be the checked exceptions in the throws 
clause of the invocation type of the method reference's compile-time declaration 
($15.13.2) (as derived from the function type's parameter types and return type). 
Then there are two cases: 


— Ifn =o (the function type's throws clause consists only of proper types), then 
if there exists some i (1 <i <m) such that x; is not a subtype of any proper type 
in the throws clause, the constraint reduces to false; otherwise, the constraint 
reduces to true. 


— Ifn> 0, the constraint reduces to a set of subtyping constraints: for all i (1 < 
i<m), if x; is not a subtype of any proper type in the throws clause, then the 
constraints include, for all j (1 <j <n), <x; <: £;. In addition, for all 7 (1 <j 
<n), the constraint reduces to the bound throws £;. 


Constraints on checked exceptions are handled separately from constraints on return 
types, because return type compatibility influences applicability of methods (§18.5.1), 
while exceptions only influence the invocation type after overload resolution is complete 
(§18.5.2). This could be simplified by including exception compatibility in the definition 
of lambda expression compatibility (§15.27.3), but this would lead to possibly surprising 
cases in which exceptions that can be thrown by an explicitly typed lambda body change 
overload resolution. 


The exceptions thrown by a lambda body cannot be determined until (i) the parameter 
types of the lambda are known, and (ii) the target type of result expressions in the body is 
known. (The second requirement is to account for generic method invocations in which, 
for example, the same type parameter appears in the return type and the throws clause.) 
Hence, we require both of these, as derived from the target type T, to be proper types. 


One consequence is that lambda expressions returned from other lambda expressions 
cannot generate constraints from their thrown exceptions. These constraints can only be 
generated from top-level lambda expressions. 


Note that the handling of the case in which more than one inference variable appears in a 
function type's throws clause is not completeness-preserving. Either variable may, on its 
own, satisfy the constraint that each checked exception be declared, but we cannot be sure 
which one is intended. So, for predictability, we constrain them both. 
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18.3 Incorporation 


As bound sets are generated and grown during inference, it is possible that new 
bounds can be inferred based on the assertions of the original bounds. The process 
of incorporation identifies these new bounds and adds them to the bound set. 


Incorporation can happen in two scenarios. One scenario is that the bound set 
contains complementary pairs of bounds; this implies new constraint formulas, 
as specified in §18.3.1. The other scenario is that the bound set contains a 
bound involving capture conversion; this implies new bounds and may imply new 
constraint formulas, as specified in §18.3.2. In both scenarios, any new constraint 
formulas are reduced, and any new bounds are added to the bound set. This may 
trigger further incorporation; ultimately, the set will reach a fixed point and no 
further bounds can be inferred. 


If incorporation of a bound set has reached a fixed point, and the set does not contain 
the bound false, then the bound set has the following properties: 


¢ For each combination of a proper lower bound z and a proper upper bound u of 
an inference variable, 1 <: v. 


¢ If every inference variable mentioned by a bound has an instantiation, the bound 
is satisfied by the corresponding substitution. 


* Given a dependency o = B, every bound of @ matches a bound of B, and vice 
versa. 


¢ Given a dependency a <: 8, every lower bound of © is a lower bound of B, and 
every upper bound of B is an upper bound of a. 


The assertion that incorporation reaches a fixed point oversimplifies the matter slightly. 
Building on the work of Kennedy and Pierce, On Decidability of Nominal Subtyping with 
Variance, this property can be proven by making the argument that the set of types that 
may appear in the bound set is finite. The argument relies on two assumptions: 


¢ New capture variables are not generated when reducing subtyping constraints (§ 18.2.3). 
e Expansive inheritance paths are not pursued. 

This specification does not currently guarantee these properties (it is imprecise about the 
handling of wildcards when reducing subtyping constraints, and does not detect expansive 


inheritance paths), but may do so in a future version. (This is not a new problem: the Java 
subtyping algorithm is also at risk of non-termination.) 


TYPE INFERENCE Incorporation 


18.3.1 Complementary Pairs of Bounds 


(In this section, s and rare inference variables or types, and vis a proper type. For 
conciseness, a bound of the form a = rT may also match a bound of the form T= a.) 


When a bound set contains a pair of bounds that match one of the following rules, 
anew constraint formula is implied: 


* a@=sanda=rimply <s= Pp 

* @=sando<: Timply<s<: p 

* @=sand Tr<: QMimply <r<: 

* s<: Qanda@<: Timply<s<: p 

* @=vand s= Timply <s[O:=uU] = T[O:=U]> 

* @=vand s<: Timply <s[Q:=uU] <: T[O:=U]> 


When a bound set contains a pair of bounds @ <: sand <: T, and there exists a 
supertype of s of the form c<sy, ..., S,> and a supertype of r of the form G<Tj, ..., 
T,> (for some generic class or interface, c), then for alli (1 <i <n), if s; and 7, are 
types (not wildcards), the constraint formula <s; = T, is implied. 


18.3.2 Bounds Involving Capture Conversion 


When a bound set contains a bound of the form c<Q;, ..., &,> = capture(G<Aj, ..., 
An>), new bounds are implied and new constraint formulas may be implied, as 
follows. 


Let P), ..., P» represent the type parameters of cand let B;, ..., B, represent the bounds 
of these type parameters. Let 8 represent the substitution [P;:=0, ..., Py!=O,]. Let 
R be a type that is not an inference variable (but is not necessarily a proper type). 


A set of bounds on Q;, ..., &, is implied, generated from the declared bounds of 
Pj, ..., Py aS Specified in §18.1.3. 


In addition, for alli (1 Sis<n): 
¢ If a, is not a wildcard, then the bound o,; = A; is implied. 
e If a; is a wildcard of the form ?: 

— Q,; = Rimplies the bound false 

— Q; <: Rimplies the constraint formula <B,; 0 <: R» 


— R<: Q,; implies the bound false 
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e If a; is a wildcard of the form 2? extends T: 
— Q; = Rimplies the bound false 
— If B; is Object, then O; <: R implies the constraint formula <T <: R» 
— If Tis object, then o; <: Rimplies the constraint formula <B; 8 <: R 
— R<: Q; implies the bound false 

e If a; is a wildcard of the form ? super T: 
— Q; = Rimplies the bound false 
— Q,; <: Rimplies the constraint formula <B,; 8 <: R» 


— R<: Q,; implies the constraint formula <R<: PD 


18.4 Resolution 


Given a bound set that does not contain the bound false, a subset of the inference 
variables mentioned by the bound set may be resolved. This means that a 
satisfactory instantiation may be added to the set for each inference variable, until 
all the requested variables have instantiations. 


Dependencies in the bound set may require that the variables be resolved in 
a particular order, or that additional variables be resolved. Dependencies are 
specified as follows: 


¢ Given a bound of one of the following forms, where r is either an inference 
variable B or a type that mentions B: 


—Q=T 
-Q<: T 
—- T=Q 
—T<:@Q@ 


If & appears on the left-hand side of another bound of the form «<x..., @, ...> = 
capture(c<...>), then B depends on the resolution of o. Otherwise, « depends on 
the resolution of B. 


e An inference variable & appearing on the left-hand side of a bound of the form 
G<..., O, ...> = capture(G<...>) depends on the resolution of every other inference 
variable mentioned in this bound (on both sides of the = sign). 
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¢ An inference variable & depends on the resolution of an inference variable B if 
there exists an inference variable y such that o depends on the resolution of y and 
y depends on the resolution of B. 


¢ An inference variable & depends on the resolution of itself. 


Given a set of inference variables to resolve, let v be the union of this set and all 
variables upon which the resolution of at least one variable in this set depends. 


If every variable in v has an instantiation, then resolution succeeds and this 
procedure terminates. 


Otherwise, let { 0, ..., &, } be a non-empty subset of uninstantiated variables in 
v such that (i) for all i (1 <i <n), if &; depends on the resolution of a variable B, 
then either B has an instantiation or there is some j such that B = 0; and (ii) there 
exists no non-empty proper subset of { 0t;, .... &, } with this property. Resolution 
proceeds by generating an instantiation for each of Q;, ..., &, based on the bounds 
in the bound set: 


e If the bound set does not contain a bound of the form c<..., Q;, ..> = 
capture(c<...>) for all i (1 <i <n), then a candidate instantiation Tr, is defined 
for each O,: 


— If a, has one or more proper lower bounds, 1, ..., L,, then T; = lub(1;, ..., 
Lx) (§4.10.4). 


— Otherwise, if the bound set contains throws ;, and each proper upper bound 
of 0; is a supertype of RuntimeException, then T; = RuntimeException. 


— Otherwise, where a; has proper upper bounds U;, ..., U,, T; = glb(U:, ..., Ux) 
(§5.1.10). 


The bounds Q, = 1), ..., , = T, are incorporated with the current bound set. 


If the result does not contain the bound false, then the result becomes the 
new bound set, and resolution proceeds by selecting a new set of variables to 
instantiate (if necessary), as described above. 


Otherwise, the result contains the bound false, so a second attempt is made to 
instantiate { O;, ..., &, } by performing the step below. 


¢ If the bound set contains a bound of the form cx..., O;, ...> = capture(c<...>) for 
some i (1 <i <n), or; 


If the bound set produced in the step above contains the bound false; 


then let y;, ..., ¥, be fresh type variables whose bounds are as follows: 
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— For alli (1 <i<n), if a; has one or more proper lower bounds 1), ..., Lx, then 
let the lower bound of y; be lub(z,, ..., 1,); if not, then y,; has no lower bound. 


— For alli (1 <i <n), where a; has upper bounds vj, ..., u;,, let the upper bound 
of y; be glb(u; 9, ..., u, 8), where 0 is the substitution [00;:=¥:, ..., Un!=Ynl. 


If the type variables y,, ..., y, do not have well-formed bounds (that is, a lower 
bound is not a subtype of an upper bound, or an intersection type is inconsistent), 
then resolution fails. 


Otherwise, for all i (1 < i < n), all bounds of the form «x..., Q,, ...> = 
capture(G<...>) are removed from the current bound set, and the bounds a, 
Y1, .«-, On = Y, are incorporated. 


If the result does not contain the bound false, then the result becomes the 
new bound set, and resolution proceeds by selecting a new set of variables to 
instantiate (if necessary), as described above. 


Otherwise, the result contains the bound false, and resolution fails. 


The first method of instantiating an inference variable derives the instantiation from that 
variable's bounds. Sometimes, however, complex dependencies mean that the result is not 
within the variable's bounds. In that case, a different method of instantiation is performed, 
analogous to capture conversion (§5.1.10): fresh type variables are introduced, with bounds 
derived from the bounds of the inference variables. Note that the lower bounds of these 
"capture" variables are computed using only proper types: this is important in order to avoid 
attempts to perform typing computations on uninstantiated type variables. 


18.5 Uses of Inference 


Using the inference processes defined above, the following analyses are performed 
at compile time. 


18.5.1 Invocation Applicability Inference 


Given a method invocation that provides no explicit type arguments, the process 
to determine whether a potentially applicable generic method m is applicable is as 
follows: 


¢ Where P:, ..., Pp (p 2 1) are the type parameters of m, let O;, ..., Op be inference 
variables, and let 6 be the substitution [P1:=0;, ..., Pp:=Qp]. 


¢ An initial bound set, By, is generated from the declared bounds of Py, ..., Pp, as 
described in §18.1.3. 
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¢ Foralli(1 <i<p), if P; appears in the throws clause of m, then the bound throws 
a; is implied. These bounds, if any, are incorporated with By to produce a new 
bound set, By. 


¢ A set of constraint formulas, c, is generated as follows. 


Let F;, ..., F, be the formal parameter types of m, and let e, ..., e, be the actual 
argument expressions of the invocation. Then: 


— To test for applicability by strict invocation: 


If k #n, or if there exists an i (1 <i <n) such that e; is pertinent to applicability 
($15.12.2.2) and either (i) e; is a standalone expression of a primitive type but 
F; 18 a reference type, or (ii) F; is a primitive type but e; is not a standalone 
expression of a primitive type; then the method is not applicable and there is 
no need to proceed with inference. 


Otherwise, c includes, for all i(1 <i < k) where e; is pertinent to applicability, 
<ei J Fi >. 


— To test for applicability by loose invocation: 


If k #n, the method is not applicable and there is no need to proceed with 
inference. 


Otherwise, c includes, for all i(1 <i < k) where e; is pertinent to applicability, 
<ei J Fi >. 


— To test for applicability by variable arity invocation: 


Let F';, ..., F'; be the first k variable arity parameter types of m(§15.12.2.4). c 
includes, for all i(1 <i <k) where e; is pertinent to applicability, <e; > F'; @. 


¢ cis reduced ($18.2) and the resulting bounds are incorporated with B, to produce 
a new bound set, Bo. 


¢ Finally, the method m is applicable if B, does not contain the bound false and 
resolution of all the inference variables in Bz succeeds (§18.4). 


Consider the following method invocation and assignment: 
List<Number> ln = Arrays.asList(1l, 2.0); 


A most specific applicable method for the invocation must be identified as described in 
§15.12. The only potentially applicable method (§15.12.2.1) is declared as follows: 


public static <T> List<T> asList(T... a) 
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Trivially (because of its arity), this method is neither applicable by strict invocation 
(§15.12.2.2) nor applicable by loose invocation (§15.12.2.3). But since there are no other 
candidates, in a third phase the method is checked for applicability by variable arity 
invocation. 


The initial bound set, B, is a trivial upper bound for a single inference variable, a: 


{ a<: Object } 


The initial constraint formula set is as follows: 


{<1 >, «2.0 9 } 


These are reduced to a new bound set, By: 


{ O<: Object, Integer <: O, Double <: @ } 


Then, to test whether the method is applicable, we attempt to resolve these bounds. We 
succeed, producing the rather complex instantiation 


Q=Number & Comparable<? extends Number & Comparable<?>> 


We have thus demonstrated that the method is applicable; since no other candidates exist, 
it is the most specific applicable method. Still, the type of the method invocation, and its 
compatibility with the target type in the assignment, is not determined until further inference 
can occur, as described in the next section. 


18.5.2 Invocation Type Inference 


Given a method invocation expression that provides no explicit type arguments, 
and a corresponding most specific applicable generic method m, the process to 
infer the invocation type (§15.12.2.6) of the chosen method may require resolving 
additional constraints, both to assert compatibility with a target type and to assert 
validity of the method invocation's argument expressions. 


It is important to note that multiple "rounds" of inference are involved in finding the type of 
a method invocation. This is necessary, for example, to allow a target type to influence the 
type of the invocation without allowing it to influence the choice of an applicable method. 
The first round (§18.5.1) produces a bound set and tests that a resolution exists, but does 
not commit to that resolution. Subsequent rounds reduce additional constraints until a final 
resolution step determines the "real" type of the expression. 


18.5.2.1. Poly Method Invocation Compatibility 


If the method invocation expression is a poly expression ($15.12), its compatibility 
with a target type Tis determined as follows. 
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If the method invocation expression appears in a strict invocation context and Tis 
a primitive type, the expression is not compatible with T. 


Otherwise: 


¢ Let B, be the bound set produced by reduction in order to demonstrate that m is 
applicable in §18.5.1. 


(While it was necessary in §18.5.1 to demonstrate that the inference variables 
in Bz could be resolved, in order to establish applicability, the instantiations 
produced by this resolution step are not considered part of B>.) 


e Let B; be the bound set derived from B, as follows. 


Let R be the return type of m, and let © be the substitution [P1:=0;, ..., Ppi=Op] 
defined in §18.5.1 to replace the type parameters of m with inference variables, 
and let r be the invocation's target type. Then: 


— If unchecked conversion was necessary for the method to be applicable during 
constraint set reduction in §18.5.1, the constraint formula <|z] > > is reduced 
and incorporated with Bp. 


— Otherwise, if R @ is a parameterized type, G<A;, ..., An>>, and one of A, ..., An iS 
a wildcard, then, for fresh inference variables ,, ..., B,,, the constraint formula 
<G<B:, ..., Bn> > DP is reduced and incorporated, along with the bound eG<,, ..., 
B,,> = capture(G<A;, ..., A,>), with Bo. 


— Otherwise, if rR 8 is an inference variable o, and one of the following is true: 


>» Tis a reference type, but is not a wildcard-parameterized type, and either 
(i) Bz contains a bound of one of the forms @ = s or s <: @, where sis a 
wildcard-parameterized type, or (ii) Bz contains two bounds of the forms s; 
<: O& and sz <: O, where s; and sz have supertypes that are two different 
parameterizations of the same generic class or interface. 


> Tis a parameterization of a generic class or interface, c, and B, contains a 
bound of one of the forms & = s or s <: @, where there exists no type of the 
form G<...> that is a supertype of s, but the raw type |c<...>| is a supertype 
of s. 


> Tis a primitive type, and one of the primitive wrapper classes mentioned in 
§5.1.7 is an instantiation, upper bound, or lower bound for & in Bp. 


then & is resolved in Bz, and where the capture of the resulting instantiation of 
Q is u, the constraint formula <u > > is reduced and incorporated with Bp. 


— Otherwise, the constraint formula <R 8 > > is reduced and incorporated with 
Bo. 
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¢ The method invocation expression is compatible with rif B; does not contain the 


bound false and resolution of all the inference variables in B; succeeds (§18.4). 
Consider the example from the previous section: 
List<Number> 1n = Arrays.asList(1l, 2.0); 
The most specific applicable method was identified as: 
public static <T> List<T> asList(T... a) 


In order to complete type-checking of the method invocation, we must determine whether 
it is compatible with its target type, List<Number>. 


The bound set used to demonstrate applicability in the previous section, Bz, was: 


{ O<: Object, Integer <: O, Double <: @ } 


The new constraint formula set is as follows: 
{ <List<a> > List<Number>> } 


This compatibility constraint produces an equality bound for a, which is included in the 
new bound set, B;: 


{ Q<: Object, Integer <: M, Double <: O, O= Number } 


These bounds are trivially resolved: 


Q = Number 


Finally, we perform a substitution on the declared return type of asList to determine that 
the method invocation has type List <Number>; clearly, this is compatible with the target 


type. 


This inference strategy is different than the Java SE 7 Edition of The Java® Language 


Specification, which would have instantiated & based on its lower bounds (before even 
considering the invocation's target type), as we did in the previous section. This would 
result in a type error, since the resulting type is not a subtype of List<Number>. 


Under various special circumstances, based on the bounds appearing in Bp, we eagerly 
resolve an inference variable that appears as the return type of the invocation. This is to 


avoid unfortunate situations in which the usual constraint, <R 8 > TP, is not completeness- 
preserving. It is, unfortunately, possible that by eagerly resolving the variable, we are unable 
to make use of bounds that would be inferred later. It is also possible that, in some cases, 
bounds that will later be inferred from the invocation arguments (such as implicitly typed 
lambda expressions) would have caused a different outcome if they had been present in Bp. 
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Despite these limitations, the strategy allows for reasonable outcomes in typical use cases, 
and is backwards compatible with the algorithm in the Java SE 7 Edition of The Java® 
Language Specification. 


18.5.2.2 Additional Argument Constraints 


The invocation type for the chosen method is determined after considering 
additional constraints that may be implied by the argument expressions of the 
method invocation expression, as follows: 


¢ If the method invocation expression is a poly expression, let B; be the bound set 
generated in §18.5.2.1 to demonstrate compatibility with the actual target type 
of the method invocation. 


If the method invocation expression is not a poly expression, let B; be the same as 
the bound set produced by reduction in order to demonstrate that mis applicable 
in §18.5.1. 


(While it was necessary in §18.5.1 and §18.5.2.1 to demonstrate that the 
inference variables in the bound set could be resolved, the instantiations 
produced by these resolution steps are not considered part of B3.) 


¢ A set of constraint formulas, c, is generated as follows. 


Let e;, ..., ex be the actual argument expressions of the method invocation 
expression. 


If mis applicable by strict or loose invocation, let F;, ..., F, be the formal parameter 
types of m; if mis applicable by variable arity invocation, let F;, ..., F, the first k 
variable arity parameter types of m(§15.12.2.4). 


Let 0 be the substitution [P1:=0t;, ..., Pp:=Q,] defined in §18.5.1 to replace the 
type parameters of m with inference variables. 


Then, for alli (1 <i<k): 
— If e; is not pertinent to applicability, c contains <e; > F; 0. 
— Additional constraints may be included, depending on the form of e;: 


> If e; is a LambdaExpression, c contains <LambdaExpression > throws Fi, 
and the lambda body is searched for additional constraints: 


» For a block lambda body, the search is applied recursively to each result 
expression. 


» For a poly class instance creation expression or a poly method invocation 
expression , Cc contains all the constraint formulas that would appear in the 
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set c generated by §18.5.2 when inferring the poly expression's invocation 
type. 

» For a parenthesized expression, the search is applied recursively to the 
contained expression. 


» For a conditional expression, the search is applied recursively to the 
second and third operands. 


» For a lambda expression, the search is applied recursively to the lambda 
body. 


If e; is a MethodReference, c contains «MethodReference > throws Fi 9. 


If e; is a poly class instance creation expression or a poly method invocation 
expression, c contains all the constraint formulas that would appear in the set 
c generated by §18.5.2 when inferring the poly expression's invocation type. 


If e; is a parenthesized expression, these rules are applied recursively to the 
contained expression. 


If e; is a conditional expression, these rules are applied recursively to the 
second and third operands. 


¢ While cis not empty, the following process is repeated, starting with the bound 
set B; and accumulating new bounds into a "current" bound set, ultimately 
producing a new bound set, B,: 


1. 


A subset of constraints is selected in c, satisfying the property that, for each 
constraint, no input variable can influence an output variable of another 
constraint in c. The terms input variable and output variable are defined 
below. An inference variable can influence an inference variable B if o 
depends on the resolution of B (§18.4), or vice versa; or if there exists a third 
inference variable y such that & can influence y and y can influence B. 


If this subset is empty, then there is a cycle (or cycles) in the graph of 
dependencies between constraints. In this case, the constraints in c that 
participate in a dependency cycle (or cycles) and do not depend on any 
constraints outside of the cycle (or cycles) are considered. A single constraint 
is selected from these considered constraints, as follows: 


— If any of the considered constraints have the form <Expression > TP, 
then the selected constraint is the considered constraint of this form that 
contains the expression to the left ($3.5) of the expression of every other 
considered constraint of this form. 
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— If no considered constraint has the form <Expression > 1m, then the 
selected constraint is the considered constraint that contains the expression 
to the left of the expression of every other considered constraint. 


2. The selected constraint(s) are removed from c. 
The input variables 0;, ..., &, of all the selected constraint(s) are resolved. 


4. Where T, ..., Tm are the instantiations of Q,, ..., Q,, the substitution 
[O7:=T}, ..., Uni=Tm] 18 applied to every constraint. 


5. The constraint(s) resulting from substitution are reduced and incorporated 
with the current bound set. 


¢ Finally, if B, does not contain the bound false, the inference variables in B, are 
resolved. 


If resolution succeeds with instantiations 1, ..., 7, for inference variables 0, ..., 
Op, let O' be the substitution [Py:=T7), ..., Ppi=Tp]. Then: 


— If unchecked conversion was necessary for the method to be applicable during 
constraint set reduction in §18.5.1, then the parameter types of the invocation 
type of m are obtained by applying 6' to the parameter types of m's type, and 
the return type and thrown types of the invocation type of m are given by the 
erasure of the return type and thrown types of z's type. 


— If unchecked conversion was not necessary for the method to be applicable, 
then the invocation type of mis obtained by applying 8' to the type of m. 


If B, contains the bound false, or if resolution fails, then a compile-time error 
occurs. 


The process of reducing additional argument constraints may require carefully 
ordering constraint formulas of the forms <Expression > tT, <LambdaExpression 
throws Tr, and <MethodReference > jhyows T. To facilitate this ordering, the input 
variables of these constraints are defined as follows: 


¢ For <LambdaExpression > T>: 
— If ris an inference variable, it is the (only) input variable. 


— If ris a functional interface type, and a function type can be derived from 
T (§15.27.3), then the input variables include (i) if the lambda expression 
is implicitly typed, the inference variables mentioned by the function type's 
parameter types; and (ii) if the function type's return type, R, is not voia, then 
for each result expression e in the lambda body (or for the body itself if it is 
an expression), the input variables of <e > R>. 
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— Otherwise, there are no input variables. 
¢ For <LambdaExpression > throws T>: 
— If ris an inference variable, it is the (only) input variable. 


— If ris a functional interface type, and a function type can be derived, as 
described in §15.27.3, the input variables include (i) if the lambda expression 
is implicitly typed, the inference variables mentioned by the function type's 
parameter types; and (ii) the inference variables mentioned by the function 
type's return type. 


— Otherwise, there are no input variables. 
¢ For <MethodReference > Tt: 
— If ris an inference variable, it is the (only) input variable. 


— If ris a functional interface type with a function type, and if the method 
reference is inexact (§$15.13.1), the input variables are the inference variables 
mentioned by the function type's parameter types. 


— Otherwise, there are no input variables. 
¢ For <MethodReference > jpyows T>: 
— If ris an inference variable, it is the (only) input variable. 


— If ris a functional interface type with a function type, and if the method 
reference is inexact (§$15.13.1), the input variables are the inference variables 
mentioned by the function type's parameter types and the function type's return 


type. 
— Otherwise, there are no input variables. 


¢ For <Expression — 1, if Expression is a parenthesized expression: 


Where the contained expression of Expression is Expression’, the input variables 
are the input variables of <Expression' > r. 


¢ For <ConditionalExpression > T>: 


Where the conditional expression has the form e; ? e2 : e3, the input variables 
are the input variables of <ez > m and<e; 9 P. 


¢ For all other constraint formulas, there are no input variables. 


The output variables of these constraints are all inference variables mentioned by 
the type on the right-hand side of the constraint, 7, that are not input variables. 
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18.5.3 Functional Interface Parameterization Inference 


Where a lambda expression with explicit parameter types P, ..., P, targets a 
functional interface type F<A;, ..., An> With at least one wildcard type argument, 
then a parameterization of Fr may be derived as the ground target type of the lambda 
expression as follows. 


Let Q:, ..., Q, be the parameter types of the function type of the type F<Q;, ..., On>, 
where Q;, ..., &, are fresh inference variables. 


Ifn #k, no valid parameterization exists. Otherwise, a set of constraint formulas is 
formed with, for all i (1 <i <n), <P; = O;>. This constraint formula set is reduced 
to form the bound set B. 


If B contains the bound false, no valid parameterization exists. Otherwise, a new 
parameterization of the functional interface type, F<A";, ..., A'n>, is constructed as 
follows, for 1 <i<m: 


¢ If 8 contains an instantiation (§18.1.3) for o;, 7, then a’, = T. 
¢ Otherwise, A’; = A,. 


If F<a';, ..., A'n> is not a well-formed type (that is, the type arguments are 
not within their bounds), or if F<A';, ..., A'n> iS not a subtype of F<A;, ..., 
An>, no valid parameterization exists. Otherwise, the inferred parameterization is 
either F<A';, ..., A'n>, if all the type arguments are types, or the non-wildcard 
parameterization (§9.9) of F<A';, ..., A'n>, if one or more type arguments are still 
wildcards. 


In order to determine the function type of a wildcard-parameterized functional interface, 
we have to "instantiate" the wildcard type arguments with specific types. The "default" 
approach is to simply replace the wildcards with their bounds, as described in §9.8, but this 
produces spurious errors in cases where a lambda expression has explicit parameter types 
that do not correspond to the wildcard bounds. For example: 


Predicate<? super Integer> p = (Number n) -> n.equals (23); 


The lambda expression is a Predicate<Number>, which is a subtype of Predicate<? 
super Integer> but not Predicate<Integer>. The analysis in this section is used to 
infer that Number is an appropriate choice for the type argument to Predicate. 


That said, the analysis here, while described in terms of general type inference, is 
intentionally quite simple. The only constraints are equality constraints, which means that 
reduction amounts to simple pattern matching. A more powerful strategy might also infer 
constraints from the body of the lambda expression. But, given possible interactions with 
inference for surrounding and/or nested generic method invocations, this would introduce 
a lot of extra complexity. 
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18.5.4 More Specific Method Inference 


When testing that one applicable method is more specific than another (§15.12.2.5), 
where the second method is generic, it is necessary to test whether some 
instantiation of the second method's type parameters can be inferred to make the 
first method more specific than the second. 


Let m, be the first method and mz be the second method. Where m, has type 
parameters P;, ..., Pp, let O, ..., Op, be inference variables, and let 0 be the 
substitution [P7:=0t1, ..., Pp'=Op]. 


Let e;, ..., ex be the argument expressions of the corresponding invocation. Then: 


¢ If m, and mz are applicable by strict or loose invocation (§15.12.2.2, §15.12.2.3), 
then let sj, ..., s, be the formal parameter types of m;, and let 1), ..., 7, be the 
result of 6 applied to the formal parameter types of mp. 


¢ If m, and mz are applicable by variable arity invocation (§15.12.2.4), then let s;, ..., 
Ss, be the first k variable arity parameter types of mj, and let 7, ..., T, be the result 
of 8 applied to the first k variable arity parameter types of m2. 


Note that no substitution is applied to Sz, ..., S;; even if m; is generic, the type parameters 
of mz are treated as type variables, not inference variables. 


The process to determine if m; is more specific than mz is as follows: 


¢ First, an initial bound set, B, is generated from the declared bounds of Py, ..., Pp, 
as specified in §18.1.3. 


¢ Second, for alli (1 <i<k), a set of constraint formulas or bounds is generated. 


If 7; is a proper type, the result is true if s; is more specific than T; for e; 
(§15.12.2.5), and false otherwise. (Note that s; is always a proper type.) 


Otherwise, if s; and 7; are not both functional interface types, the constraint 
formula <s; <: T;> is generated. 


Otherwise, if the interface of s; is a superinterface or a subinterface of the 
interface of T; (or, where s; or T; is an intersection type, some interface of s; is a 
superinterface or a subinterface of some interface of T;), the constraint formula 
<S; <: T»> 1s generated. 


Otherwise, let ur; be the function type of the capture of s,, let mr.' be the 
function type of s; (without capture), and let mr; be the function type of 1;. If 
MT; and mT, have a different number of formal parameters or type parameters, or 
if mT; and mr,’ do not have the same type parameters (§8.4.4), the result is false. 
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Otherwise, the following constraint formulas or bounds are generated from the 
type parameters, formal parameter types, and return types of wr; and mT: 


— Let 


Aj, ..., An be the type parameters of mrs, and let B;, ..., B, be the type 


parameters of Tv. 


Let 0' be the substitution [B;:=A;, ..., By!=A,]. Then, for all 7 (1 <j <n): 


>» If the bound of a; mentions one of A;, ..., An, and the bound of 8; is a not 
proper type, false. 


> Otherwise, where x is the bound of a; and y is the bound of B,, <x= y 0». 


— Let 


If the bound A; mentions one of A;, ..., An, and the bound of B, is not a proper 
type, then producing an equality constraint would raise the possibility of an inference 
variable being bounded by an out-of-scope type variable. Since instantiating an 
inference variable with an out-of-scope type variable is nonsensical, we prefer to 
avoid the situation by giving up immediately whenever the possibility arises. This 
simplification is not completeness-preserving. (The same comment applies to the 
treatment of formal parameter types and return types below.) 


U1, ..., Ux be the formal parameter types of mrs, and let vj, ..., Vv. be the 


formal parameter types of ur,r. Then, for all j (1 <j <k): 


>» If vu; mentions one of A;, ..., An, and Vv; is not a proper type, false. 


>» Otherwise, <v; 0' <: u», and, where u,', ..., U,;' are the formal parameter 
types of mr,', and Aj’, ..., A,’ are the type parameters of mT.', <Vj[By!=A1', ..., 
Byi=Ap'] = U;> 


— Let rR; be the return type of urs, and let rR; be the return type of ur;. Then: 


>» If R; mentions one of Aj, ..., An, and Reis not a proper type, false. 


» Otherwise, if e; is an explicitly typed lambda expression: 


» 


» 


» 


» 


If Rr 1S void, true. 


Otherwise, if R; and R; are functional interface types, and e; has at least 
one result expression, then for each result expression in e,, this entire 
second step is repeated to infer constraints under which Rg is more specific 
than R; 6' for the given result expression. 


Otherwise, if Rs is a primitive type and R; is not, and e; has at least 
one result expression, and each result expression of e; is a standalone 
expression (§15.2) of a primitive type, true. 


Otherwise, if R; is a primitive type and R,; is not, and e; has at least one 
result expression, and each result expression of e; is either a standalone 
expression of a reference type or a poly expression, true. 
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» Otherwise, <Rs <: R798. 
>» Otherwise, if e; is an exact method reference: 
» If Rr is void, true. 


» Otherwise, if R; is a primitive type and R; is not, and the compile-time 
declaration for e; has a primitive return type, true. 


» Otherwise if Rr is a primitive type and Rg, is not, and the compile-time 
declaration for e; has a reference return type, true. 


» Otherwise, <R; <: R7@>. 


» Otherwise, if e; is a parenthesized expression, these rules for constraints 
derived from rR; and R; are applied recursively for the contained expression. 


» Otherwise, if e; is a conditional expression, these rules for constraints 
derived from rR; and R; are applied recursively for each of the second and 
third operands. 


» Otherwise, false. 


¢ Third, if mz is applicable by variable arity invocation and has k+1 parameters, 
then where s;,; is the k+1'th variable arity parameter type of m, and T,,; is the 
result of 6 applied to the k+1'th variable arity parameter type of mz, the constraint 
<Sxr1 <: Tx+7 iS generated. 


¢ Fourth, the generated bounds and constraint formulas are reduced and 
incorporated with B to produce a bound set B’. 


If B' does not contain the bound false, and resolution of all the inference variables 
in B' succeeds, then m, is more specific than mp. 


Otherwise, m; is not more specific than mp. 


CHAPTER 19 


Syntax 


Tuts chapter repeats the syntactic grammar given in Chapters 4, 6-10, 14, and 
15, as well as key parts of the lexical grammar from Chapter 3, using the notation 
from §2.4. 


Productions from §3 (Lexical Structure) 


Identifier: 
IdentifierChars but not a Keyword or BooleanLiteral or NullLiteral 


IdentifierChars: 
JavaLetter {JavaLetterOrDigit} 


JavaLetter: 
any Unicode character that is a "Java letter" 


JavaLetterOrDigit: 
any Unicode character that is a "Java letter-or-digit" 


Typeldentifier: 
Identifier but not var 


Literal: 
IntegerLiteral 
FloatingPointLiteral 
BooleanLiteral 
CharacterLiteral 
StringLiteral 
NullLiteral 
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Productions from §4 (Types, Values, and Variables) 


Type: 
PrimitiveType 
ReferenceType 


PrimitiveType: 
{Annotation} NumericType 
{Annotation} boolean 


NumericType: 
IntegralType 
FloatingPointType 


IntegralType: 
(one of) 


byte short int long char 


FloatingPointType: 
(one of) 


float double 


ReferenceType: 
ClassOrInterfaceType 
TypeVariable 
ArrayType 


ClassOrInterfaceType: 
ClassType 
InterfaceType 


ClassType: 
{Annotation} Typeldentifier [TypeArguments ] 
PackageName . {Annotation} Typeldentifier [TypeArguments] 
ClassOrInterfaceType . {Annotation} Typeldentifier [TypeArguments] 


InterfaceType: 
ClassType 


Type Variable: 
{Annotation} Typeldentifier 
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ArrayType: 
PrimitiveType Dims 
ClassOrInterfaceType Dims 
TypeVariable Dims 


Dims: 
{Annotation} {| | {{Annotation} [ ]} 


TypeParameter: 
{TypeParameterModifier} Typeldentifier [TypeBound] 


TypeParameterModifier: 
Annotation 


TypeBound: 
extends TypeVariable 
extends ClassOrInterfaceType {AdditionalBound} 


AdditionalBound: 
& InterfaceType 


TypeArguments: 
< TypeArgumentList > 


TypeArgumentList: 
TypeArgument {, TypeArgument} 


TypeArgument: 
ReferenceType 
Wildcard 


Wildcard: 
{Annotation} 2 [WildcardBounds ] 


WildcardBounds: 
extends ReferenceType 
super ReferenceType 


725 
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ModuleName: 
Identifier 
ModuleName . Identifier 


PackageName: 
Identifier 
PackageName . Identifier 


TypeName: 
Typeldentifier 
PackageOrTypeName . Typeldentifier 


ExpressionName: 
Identifier 
AmbiguousName . Identifier 


MethodName: 
Identifier 


PackageOrTypeName: 
Identifier 
PackageOrTypeName . Identifier 


AmbiguousName: 


Identifier 
AmbiguousName . Identifier 
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Productions from §7 (Packages and Modules) 


CompilationUnit: 
Ordinary CompilationUnit 
ModularCompilationUnit 


OrdinaryCompilationUnit: 
[PackageDeclaration] {ImportDeclaration} {TypeDeclaration} 


ModularCompilationUnit: 
{ImportDeclaration} ModuleDeclaration 


PackageDeclaration: 
{PackageModifier} package Identifier {. Identifier} ; 


PackageModifier: 
Annotation 


ImportDeclaration: 
SingleTypelmportDeclaration 
TypeIlmportOnDemandDeclaration 
SingleStaticlmportDeclaration 
StaticImportOnDemandDeclaration 


SingleTypelmportDeclaration: 
import TypeName ; 


TypelmportOnDemanadDeclaration: 
import PackageOrTypeName . * ; 


SingleStaticImportDeclaration: 
import static TypeName . Identifier ; 


StaticImportOnDemandDeclaration: 
import static TypeName . * ; 


TypeDeclaration: 
ClassDeclaration 
InterfaceDeclaration 


’ 
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ModuleDeclaration: 
{Annotation} [open] module Identifier { . Identifier} 
{ {ModuleDirective} } 


ModuleDirective: 
requires {RequiresModifier} ModuleName ; 
exports PackageName [to ModuleName {, ModuleName}] ; 
opens PackageName [to ModuleName {, ModuleName}] ; 
uses TypeName ; 
provides TypeName with TypeName {, TypeName} ; 


RequiresModifier: 
(one of) 


transitive static 
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Productions from §8 (Classes) 


ClassDeclaration: 
NormalClassDeclaration 
EnumDeclaration 


NormalClassDeclaration: 
{ClassModifier} class Typeldentifier [TypeParameters] 
[Superclass] [Superinterfaces] ClassBody 


ClassModifier: 
(one of) 
Annotation public protected private 


abstract static final strictfp 


TypeParameters: 
< TypeParameterList > 


TypeParameterList: 
TypeParameter {, TypeParameter} 


Superclass: 
extends ClassType 


Superinterfaces: 
implements InterfaceTypeList 


InterfaceTypeList: 
InterfaceType {, InterfaceType} 


ClassBody: 
{ {ClassBodyDeclaration} } 


ClassBodyDeclaration: 
ClassMemberDeclaration 
InstancelInitializer 
Staticlnitializer 
ConstructorDeclaration 
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ClassMemberDeclaration: 
FieldDeclaration 
MethodDeclaration 
ClassDeclaration 
InterfaceDeclaration 


’ 


FieldDeclaration: 
{FieldModifier} UnannType VariableDeclaratorList ; 


FieldModifier: 
(one of) 


Annotation public protected private 


static final transient volatile 


VariableDeclaratorList: 
VariableDeclarator {, VariableDeclarator} 


VariableDeclarator: 
VariableDeclaratorld [= VariableInitializer] 


VariableDeclaratorld: 
Identifier [Dims] 


Variablelnitializer: 


Expression 
Arraylnitializer 
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UnannType: 
UnannPrimitiveType 
UnannReferenceType 


UnannPrimitiveType: 
NumericType 


boolean 


UnannReferenceType: 
UnannClassOrInterfaceType 
UnannTypeVariable 
UnannArrayType 


UnannClassOrInterfaceType: 
UnannClassType 
UnannInterfaceType 


UnannClassType: 
Typeldentifier [TypeArguments ] 
PackageName . {Annotation} Typeldentifier [TypeArguments] 
UnannClassOrInterfaceType . {Annotation} Typeldentifier 
[TypeArguments ] 


UnannInterfaceType: 
UnannClassType 


UnannTypeVariable: 
Typeldentifier 


UnannArrayType: 
UnannPrimitiveType Dims 
UnannClassOrInterfaceType Dims 
UnannTypeVariable Dims 
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MethodDeclaration: 
{MethodModifier} MethodHeader MethodBody 


MethodModifier: 
(one of) 


Annotation public protected private 


abstract static final synchronized native strictfp 


MethodHeader: 
Result MethodDeclarator [Throws] 
TypeParameters {Annotation} Result MethodDeclarator [Throws] 


Result: 
UnannType 


void 


MethodDeclarator: 
Identifier ( [ReceiverParameter ,] [FormalParameterList] ) [Dims] 


ReceiverParameter: 
{Annotation} UnannType [Identifier .] this 


FormalParameterList: 
FormalParameter {, FormalParameter} 


FormalParameter: 
{ VariableModifier} UnannType VariableDeclaratorld 
VariableArityParameter 


VariableArity Parameter: 
{ VariableModifier} UnannType {Annotation} ... Identifier 


VariableModifier: 
Annotation 


final 


Throws: 
throws ExceptionTypeList 


ExceptionTypeList: 
ExceptionType {, ExceptionType} 
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ExceptionType: 
ClassType 
TypeVariable 


MethodBody: 
Block 


’ 


Instancelnitializer: 
Block 


StaticInitializer: 
static Block 


ConstructorDeclaration: 
{ConstructorModifier} ConstructorDeclarator [Throws] ConstructorBody 


ConstructorModifier: 


(one of) 


Annotation public protected private 


ConstructorDeclarator: 
[TypeParameters ] SimpleTypeName 
( [ReceiverParameter , ] [FormalParameterList] ) 


SimpleTypeName: 
Typeldentifier 


ConstructorBody: 
{ [ExplicitConstructorInvocation] [BlockStatements] } 


ExplicitConstructorInvocation: 
[TypeArguments] this ( [ArgumentList] ) ; 
[TypeArguments] super ( [ArgumentList] ) ; 
ExpressionName . [TypeArguments] super ( [ArgumentList] ) ; 
Primary . [TypeArguments] super ( [ArgumentList] ) ; 
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EnumDeclaration: 
{ClassModifier} enum Typeldentifier [Superinterfaces] EnumBody 


EnumBody: 
{ [EnumConstantList] [, ] [EnumBodyDeclarations] } 


EnumConstantList: 
EnumConstant {, EnumConstant} 


EnumConstant: 
{EnumConstantModifier} Identifier [ ( [ArgumentList] ) ] [ClassBody] 


EnumConstantModifier: 
Annotation 


EnumBodyDeclarations: 
; {ClassBodyDeclaration} 
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Productions from §9 (Interfaces) 


InterfaceDeclaration: 
NormalInterfaceDeclaration 
AnnotationTypeDeclaration 


NormatlInterfaceDeclaration: 
{InterfaceModifier} interface Typeldentifier [TypeParameters ] 
[ExtendsInterfaces] InterfaceBody 


InterfaceModifier: 
(one of) 
Annotation public protected private 


abstract static strictfp 


ExtendsInterfaces: 
extends InterfaceTypeList 


InterfaceBody: 
{ {InterfaceMemberDeclaration} } 


InterfaceMemberDeclaration: 
ConstantDeclaration 
InterfaceMethodDeclaration 
ClassDeclaration 
InterfaceDeclaration 


’ 


ConstantDeclaration: 
{ConstantModifier} UnannType VariableDeclaratorList ; 


ConstantModifier: 
(one of) 


Annotation public 


static final 


InterfaceMethodDeclaration: 
{InterfaceMethodModifier} MethodHeader MethodBody 
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InterfaceMethodModifier: 
(one of) 


Annotation public private 
abstract default static strictfp 


AnnotationTypeDeclaration: 
{InterfaceModifier} @ interface Typeldentifier AnnotationTypeBody 


AnnotationTypeBody: 
{ {AnnotationTypeMemberDeclaration} } 


AnnotationTypeMemberDeclaration: 
AnnotationTypeElementDeclaration 
ConstantDeclaration 
ClassDeclaration 
InterfaceDeclaration 


’ 


AnnotationTypeElementDeclaration: 
{AnnotationTypeElementModifier} UnannType Identifier ( ) [Dims] 
[DefaultValue] ; 


AnnotationTypeElementModifier: 
(one of) 


Annotation public 


abstract 


DefaultValue: 
default ElementValue 
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Annotation: 
NormalAnnotation 
MarkerAnnotation 
SingleElementAnnotation 


NormalAnnotation: 
@ TypeName ( [ElementValuePairList] ) 


ElementValuePairList: 
ElementValuePair {, ElementValuePair} 


ElementValuePair: 
Identifier = ElementValue 


ElementValue: 
ConditionalExpression 
ElementValueArraylnitializer 
Annotation 


ElementValueArraylInitializer: 
{ [ElementValueList] [, ] } 


ElementValueList: 
ElementValue {, ElementValue} 


MarkerAnnotation: 
@ TypeName 


SingleElementAnnotation: 
@ TypeName ( ElementValue ) 
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Productions from §10 (Arrays) 


Arraylnitializer: 
{ [VariablelnitializerList] [, ] } 


VariableInitializerList: 
Variablelnitializer {, VariableInitializer} 


SYNTAX 


SYNTAX 


Productions from §14 (Blocks and Statements) 


Block: 
{ [BlockStatements] } 


BlockStatements: 
BlockStatement {BlockStatement} 


BlockStatement: 
LocalVariableDeclarationStatement 
ClassDeclaration 
Statement 


LocalVariableDeclarationStatement: 
LocalVariableDeclaration ; 


LocalVariableDeclaration: 
{VariableModifier} LocalVariableType VariableDeclaratorList 


LocalVariableType: 
UnannType 


var 


Statement: 
StatementWithoutTrailing Substatement 
LabeledStatement 
IfThenStatement 
IfThenElseStatement 
WhileStatement 
ForStatement 


StatementNoShortlf: 
StatementWithoutTrailingSubstatement 
LabeledStatementNoShortlf 
IfThenElseStatementNoShortlf 
WhileStatementNoShortlf 
ForStatementNoShortlf 
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StatementWithoutTrailingSubstatement: 


Block 
EmptyStatement 
ExpressionStatement 
AssertStatement 
SwitchStatement 
DoStatement 
BreakStatement 
ContinueStatement 
ReturnStatement 
SynchronizedStatement 
ThrowStatement 
TryStatement 


EmptyStatement: 


’ 


LabeledStatement: 
Identifier : Statement 


LabeledStatementNoShortIf: 
Identifier : StatementNoShortlf 


ExpressionStatement: 
StatementExpression ; 


StatementExpression: 
Assignment 
PreIncrementExpression 
PreDecrementExpression 
PostIncrementExpression 
PostDecrementExpression 
MethodInvocation 
ClassInstanceCreationExpression 
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SYNTAX 


IfThenStatement: 
it ( Expression ) Statement 


IfThenElseStatement: 
it ( Expression ) StatementNoShortlf else Statement 


IfThenElseStatementNoShortIf: 
if ( Expression ) StatementNoShortlf else StatementNoShortlf 


AssertStatement: 
assert Expression ; 
assert Expression : Expression ; 


SwitchStatement: 
switch ( Expression ) SwitchBlock 


SwitchBlock: 
{ {SwitchBlockStatementGroup} {SwitchLabel} } 


SwitchBlockStatementGroup: 
SwitchLabels BlockStatements 


SwitchLabels: 
SwitchLabel {SwitchLabel} 


SwitchLabel: 
case ConstantExpression : 
case EnumConstantName : 
default : 


EnumConstantName: 
Identifier 


WhileStatement: 
while ( Expression ) Statement 


WhileStatementNoShortIf: 
while ( Expression ) StatementNoShortlf 


DoStatement: 
do Statement while ( Expression ) ; 
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ForStatement: 
BasicForStatement 
EnhancedForStatement 


ForStatementNoShortlf: 
BasicForStatementNoShortlf 
EnhancedForStatementNoShortlf 


BasicForStatement: 
for ([Forlnit] ; [Expression] ; [ForUpdate] ) Statement 


BasicForStatementNoShortlf: 
for ([ForInit] ; [Expression] ; [ForUpdate] ) StatementNoShortlf 


Forlnit: 
StatementExpressionList 
LocalVariableDeclaration 


ForUpdate: 
StatementExpressionList 


StatementExpressionList: 
StatementExpression {, StatementExpression} 


EnhancedForStatement: 
for ( {VariableModifier} LocalVariableType VariableDeclaratorld 
: Expression ) 
Statement 


EnhancedForStatementNoShortlf: 
for ( {VariableModifier} LocalVariableType VariableDeclaratorld 
: Expression ) 
StatementNoShortlf 


BreakStatement: 
break [Identifier] ; 


ContinueStatement: 
continue [Identifier] ; 


ReturnStatement: 
return [Expression] ; 
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ThrowStatement: 
throw Expression ; 


SynchronizedStatement: 
synchronized ( Expression ) Block 


TryStatement: 
try Block Catches 
try Block [Catches] Finally 
Try WithResourcesStatement 


Catches: 
CatchClause {CatchClause} 


CatchClause: 
catch ( CatchFormalParameter ) Block 


CatchFormalParameter: 
{VariableModifier} CatchType VariableDeclaratorId 


CatchType: 
UnannClassType {| ClassType} 


Finally: 
finally Block 


TryWithResourcesStatement: 
try ResourceSpecification Block [Catches] [Finally] 


ResourceSpecification: 
( ResourceList [; ] ) 


ResourceList: 
Resource {; Resource} 


Resource: 


{VariableModifier} LocalVariableType Identifier = Expression 
VariableAccess 
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Productions from §15 (Expressions) 


Primary: 
PrimaryNoNewArray 
ArrayCreationExpression 


PrimaryNoNewArray: 
Literal 
ClassLiteral 
this 
TypeName . this 

( Expression ) 
ClassInstanceCreationExpression 
FieldAccess 

ArrayAccess 

MethodInvocation 
MethodReference 


ClassLiteral: 
TypeName {{ |} . class 
NumericType {( 1} . class 
boolean {[ ]} . class 


void . class 


ClassInstanceCreationExpression: 
UnqualifiedClassInstanceCreationExpression 
ExpressionName . UnqualifiedClassInstanceCreationExpression 
Primary . UnqualifiedClassInstanceCreationExpression 


UnqualifiedClassInstanceCreationExpression: 
new [TypeArguments ] 
ClassOrInterfaceTypeToInstantiate ( [ArgumentList] ) [ClassBody] 


ClassOrInterfaceTypeToInstantiate: 
{Annotation} Identifier {. {Annotation} Identifier} 
[TypeArgumentsOrDiamond] 


TypeArgumentsOrDiamond: 
TypeArguments 


<> 
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FieldAccess: 
Primary . Identifier 
super . Identifier 
TypeName . super . Identifier 


ArrayAccess: 
ExpressionName [{ Expression ] 
PrimaryNoNewArray [ Expression ] 


MethodInvocation: 
MethodName ( [ArgumentList] ) 
TypeName . [TypeArguments] Identifier ( [ArgumentList] ) 
ExpressionName . [TypeArguments] Identifier ( [ArgumentList] ) 
Primary . [TypeArguments] Identifier ( [ArgumentList] ) 
super . [TypeArguments] Identifier ( [ArgumentList] ) 
TypeName . super . [TypeArguments] Identifier ( [ArgumentList] ) 


ArgumentList: 
Expression {, Expression} 


MethodReference: 
ExpressionName :: [TypeArguments] Identifier 
Primary :: [TypeArguments] Identifier 
ReferenceType :: [TypeArguments] Identifier 
super :: [TypeArguments] Identifier 
TypeName . super :: [TypeArguments] Identifier 
ClassType :: [TypeArguments] new 
ArrayType :: new 


ArrayCreationExpression: 
new PrimitiveType DimExprs [Dims] 
new ClassOrInterfaceType DimExprs [Dims] 
new PrimitiveType Dims ArrayInitializer 
new ClassOrInterfaceType Dims Arraylnitializer 


DimExprs: 
DimExpr {DimExpr} 


DimExpr: 
{Annotation} | Expression | 
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Expression: 
LambdaExpression 
AssignmentExpression 


LambdaExpression: 
LambdaParameters -> LambdaBody 


LambdaParameters: 
( [LambdaParameterList] ) 
Identifier 


LambdaParameterList: 
LambdaParameter {, LambdaParameter} 
Identifier {, Identifier} 


LambdaParameter: 
{VariableModifier} LambdaParameterType VariableDeclaratorId 
VariableArityParameter 


LambdaParameterType: 
UnannType 


var 


LambdaBody: 
Expression 
Block 


SYNTAX 


SYNTAX 


AssignmentExpression: 
ConditionalExpression 
Assignment 


Assignment: 
LeftHandSide AssignmentOperator Expression 


LeftHandSide: 
ExpressionName 
FieldAccess 
ArrayAccess 


AssignmentOperator: 


(one of) 


/ z + << >> >>> & ay 


ConditionalExpression: 
ConditionalOrExpression 
ConditionalOrExpression 2? Expression : ConditionalExpression 
ConditionalOrExpression ? Expression : LambdaExpression 


ConditionalOrExpression: 
ConditionalAndExpression 
ConditionalOrExpression | | ConditionalAndExpression 


ConditionalAndExpression: 
InclusiveOrExpression 
ConditionalAndExpression && InclusiveOrExpression 


InclusiveOrExpression: 
ExclusiveOrExpression 
InclusiveOrExpression | ExclusiveOrExpression 


ExclusiveOrExpression: 
AndExpression 
ExclusiveOrExpression * AndExpression 


AndExpression: 


EqualityExpression 
AndExpression « EqualityExpression 


747 


748 


EqualityExpression: 
RelationalExpression 
EqualityExpression == RelationalExpression 
EqualityExpression != RelationalExpression 


RelationalExpression: 
ShiftExpression 
RelationalExpression < ShiftExpression 
RelationalExpression > ShiftExpression 
RelationalExpression <= ShiftExpression 
RelationalExpression >= ShiftExpression 
RelationalExpression instanceof ReferenceType 


ShiftExpression: 
AdditiveExpression 
ShiftExpression << AdditiveExpression 
ShiftExpression >> AdditiveExpression 
ShiftExpression >>> AdditiveExpression 


AdditiveExpression: 
MultiplicativeExpression 
AdditiveExpression + MultiplicativeExpression 
AdditiveExpression - MultiplicativeExpression 


MultiplicativeExpression: 
UnaryExpression 
MultiplicativeExpression * UnaryExpression 
MultiplicativeExpression / UnaryExpression 
MultiplicativeExpression % UnaryExpression 


UnaryExpression: 
PreIncrementExpression 
PreDecrementExpression 
+ UnaryExpression 
- UnaryExpression 
UnaryExpressionNotPlusMinus 


PreIncrementExpression: 
++ UnaryExpression 


PreDecrementExpression: 
-- UnaryExpression 


SYNTAX 


SYNTAX 


UnaryExpressionNotPlusMinus: 
PostfixExpression 
~ UnaryExpression 
! UnaryExpression 
CastExpression 


PostfixExpression: 
Primary 
ExpressionName 
PostIncrementExpression 
PostDecrementExpression 


PostIncrementExpression: 
PostfixExpression ++ 


PostDecrementExpression: 
PostfixExpression -- 
CastExpression: 
( PrimitiveType ) UnaryExpression 


( ReferenceType {AdditionalBound} ) UnaryExpressionNotPlusMinus 
( ReferenceType {AdditionalBound} ) LambdaExpression 


ConstantExpression: 
Expression 
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Appendix A. Limited License Grant 


ORACLE AMERICA, INC. IS WILLING TO LICENSE THIS SPECIFICATION 
TO YOU ONLY UPON THE CONDITION THAT YOU ACCEPT ALL 
OF THE TERMS CONTAINED IN THIS AGREEMENT ("AGREEMENT"). 
PLEASE READ THE TERMS AND CONDITIONS OF THIS AGREEMENT 
CAREFULLY. 


Specification: JSR-386 Java SE 12 ("Specification") 

Version: 12 

Status: Final Release 

Specification Lead: Oracle America, Inc. ("Specification Lead") 
Release: March 2019 


Copyright © 1997, 2019, Oracle America, Inc. 
All rights reserved. 


LIMITED LICENSE GRANTS 


1. License for Evaluation Purposes. Specification Lead hereby grants you a fully- 
paid, non-exclusive, non-transferable, worldwide, limited license (without the right 
to sublicense), under Specification Lead's applicable intellectual property rights 
to view, download, use and reproduce the Specification only for the purpose 
of internal evaluation. This includes (i) developing applications intended to run 
on an implementation of the Specification, provided that such applications do 
not themselves implement any portion(s) of the Specification, and (ii) discussing 
the Specification with any third party; and (iii) excerpting brief portions of the 
Specification in oral or written communications which discuss the Specification 
provided that such excerpts do not in the aggregate constitute a significant portion 
of the Specification. 


2. License for the Distribution of Compliant Implementations. Specification Lead 
also grants you a perpetual, non-exclusive, non-transferable, worldwide, fully 
paid-up, royalty free, limited license (without the right to sublicense) under 
any applicable copyrights or, subject to the provisions of subsection 4 below, 
patent rights it may have covering the Specification to create and/or distribute an 
Independent Implementation of the Specification that: (a) fully implements the 
Specification including all its required interfaces and functionality; (b) does not 
modify, subset, superset or otherwise extend the Licensor Name Space, or include 
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any public or protected packages, classes, Java interfaces, fields or methods within 
the Licensor Name Space other than those required/authorized by the Specification 
or Specifications being implemented; and (c) passes the Technology Compatibility 
Kit (including satisfying the requirements of the applicable TCK Users Guide) 
for such Specification ("Compliant Implementation"). In addition, the foregoing 
license is expressly conditioned on your not acting outside its scope. No license 
is granted hereunder for any other purpose (including, for example, modifying 
the Specification, other than to the extent of your fair use rights, or distributing 
the Specification to third parties). Also, no right, title, or interest in or to any 
trademarks, service marks, or trade names of Specification Lead or Specification 
Lead's licensors is granted hereunder. Java, and Java-related logos, marks and 
names are trademarks or registered trademarks of Oracle America, Inc. in the U.S. 
and other countries. 


3. Pass-through Conditions. You need not include limitations (a)-(c) from the 
previous paragraph or any other particular "pass through" requirements in any 
license You grant concerning the use of your Independent Implementation 
or products derived from it. However, except with respect to Independent 
Implementations (and products derived from them) that satisfy limitations (a)-(c) 
from the previous paragraph, You may neither: (a) grant or otherwise pass through 
to your licensees any licenses under Specification Lead's applicable intellectual 
property rights; nor (b) authorize your licensees to make any claims concerning 
their implementation's compliance with the Specification in question. 


4. Reciprocity Concerning Patent Licenses. 


a. With respect to any patent claims covered by the license granted under 
subparagraph 2 above that would be infringed by all technically feasible 
implementations of the Specification, such license is conditioned upon your 
offering on fair, reasonable and non-discriminatory terms, to any party seeking it 
from You, a perpetual, non-exclusive, non-transferable, worldwide license under 
Your patent rights which are or would be infringed by all technically feasible 
implementations of the Specification to develop, distribute and use a Compliant 
Implementation. 


b. With respect to any patent claims owned by Specification Lead and covered by 
the license granted under subparagraph 2, whether or not their infringement can 
be avoided in a technically feasible manner when implementing the Specification, 
such license shall terminate with respect to such claims if You initiate a claim 
against Specification Lead that it has, in the course of performing its responsibilities 
as the Specification Lead, induced any other entity to infringe Your patent rights. 
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c. Also with respect to any patent claims owned by Specification Lead and covered 
by the license granted under subparagraph 2 above, where the infringement of 
such claims can be avoided in a technically feasible manner when implementing 
the Specification such license, with respect to such claims, shall terminate if You 
initiate a claim against Specification Lead that its making, having made, using, 
offering to sell, selling or importing a Compliant Implementation infringes Your 
patent rights. 


5. Definitions. For the purposes of this Agreement: "Independent Implementation" 
shall mean an implementation of the Specification that neither derives from any 
of Specification Lead's source code or binary code materials nor, except with 
an appropriate and separate license from Specification Lead, includes any of 
Specification Lead's source code or binary code materials; "Licensor Name Space" 
shall mean the public class or interface declarations whose names begin with 
"java", "javax", "com.oracle", "com.sun" or their equivalents in any subsequent 
naming convention adopted by Oracle America, Inc. through the Java Community 
Process, or any recognized successors or replacements thereof; and "Technology 
Compatibility Kit" or "TCK" shall mean the test suite and accompanying 
TCK User's Guide provided by Specification Lead which corresponds to the 
Specification and that was available either (i) from Specification Lead 120 days 
before the first release of Your Independent Implementation that allows its use for 
commercial purposes, or (ii) more recently than 120 days from such release but 
against which You elect to test Your implementation of the Specification. 


This Agreement will terminate immediately without notice from Specification 
Lead if you breach the Agreement or act outside the scope of the licenses granted 
above. 


DISCLAIMER OF WARRANTIES 


THE SPECIFICATION IS PROVIDED "AS IS". SPECIFICATION LEAD 
MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS 
OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES 
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
NON-INFRINGEMENT (INCLUDING AS A CONSEQUENCE OF ANY 
PRACTICE OR IMPLEMENTATION OF THE SPECIFICATION), OR THAT 
THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY 
PURPOSE. This document does not represent any commitment to release or 
implement any portion of the Specification in any product. In addition, the 
Specification could include technical inaccuracies or typographical errors. 


LIMITATION OF LIABILITY 
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TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL 
SPECIFICATION LEAD OR ITS LICENSORS BE LIABLE FOR ANY 
DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, 
PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, 
INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND 
REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF 
OR RELATED IN ANY WAY TO YOUR HAVING, IMPLEMENTING OR 
OTHERWISE USING THE SPECIFICATION, EVEN IF SPECIFICATION 
LEAD AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGES. 


You will indemnify, hold harmless, and defend Specification Lead and its licensors 
from any claims arising or resulting from: (i) your use of the Specification; (ii) the 
use or distribution of your Java application, applet and/or implementation; and/or 
(iii) any claims that later versions or releases of any Specification furnished to you 
are incompatible with the Specification provided to you under this license. 


RESTRICTED RIGHTS LEGEND 


U.S. Government: If this Specification is being acquired by or on behalf of the 
U.S. Government or by a U.S. Government prime contractor or subcontractor 
(at any tier), then the Government's rights in the Software and accompanying 
documentation shall be only as set forth in this license; this is in accordance 
with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense (DoD) 
acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions). 


REPORT 


If you provide Specification Lead with any comments or suggestions concerning 
the Specification ("Feedback"), you hereby: (i) agree that such Feedback 
is provided on a non-proprietary and non-confidential basis, and (ii) grant 
Specification Lead a perpetual, non-exclusive, worldwide, fully paid-up, 
irrevocable license, with the right to sublicense through multiple levels of 
sublicensees, to incorporate, disclose, and use without limitation the Feedback for 


any purpose. 
GENERAL TERMS 


Any action related to this Agreement will be governed by California law and 
controlling U.S. federal law. The U.N. Convention for the International Sale of 
Goods and the choice of law rules of any jurisdiction will not apply. 


The Specification is subject to U.S. export control laws and may be subject to export 
or import regulations in other countries. Licensee agrees to comply strictly with all 
such laws and regulations and acknowledges that it has the responsibility to obtain 
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such licenses to export, re-export or import as may be required after delivery to 
Licensee. 


This Agreement is the parties' entire agreement relating to its subject matter. 
It supersedes all prior or contemporaneous oral or written communications, 
proposals, conditions, representations and warranties and prevails over any 
conflicting or additional terms of any quote, order, acknowledgment, or other 
communication between the parties relating to its subject matter during the term 
of this Agreement. No modification to this Agreement will be binding, unless in 
writing and signed by an authorized representative of each party. 
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